# Code Editor Use Git-based workflows and MDX in your preferred code editor to write, organize, and publish documentation with Documentation.AI. ## Overview The code editor workflow lets you write and manage documentation in your preferred development environment (for example, VS Code, Cursor, or Windsurf). You work with `.mdx` files locally, commit changes to Git, and Documentation.AI builds and deploys from your connected repository. Use this page as the single reference for: - When to use the code editor workflow - How to write docs in MDX with Documentation.AI components - Recommended Git workflows for collaboration and previews - How to organize files and navigation with `documentation.json` If you prefer visual editing, real-time collaboration, and publishing without Git, see the [Web Editor](/content/docs/write-and-publish/web-editor/index.html). ## When to use the code editor workflow Choose the code editor workflow when you want: - **Developer workflows** Use Git branching, pull requests, code reviews, and CI-style checks. - **Bulk editing and refactors** Run project-wide search and replace, automate changes with scripts, and refactor content across many files. - **Integration with code** Keep docs in the same repo as your product code, or in a dedicated docs repo with the same tooling (linting, formatting, CI). - **Extension ecosystem** Use editor extensions for markdown linting, spell-check, formatting, and AI assistance. - **Offline work** Edit docs without internet access and push changes when you are back online. Use the [Web Editor](/content/docs/write-and-publish/web-editor/index.html) when you need: - Quick, one-off content edits without touching Git - Non-technical contributors editing docs - Visual content editing and drag-and-drop media management ## Set up your project ### 1\. Connect your repository 1. In the Documentation.AI dashboard, open **Settings → Git Settings**. 2. Connect your Git provider (GitHub, GitLab, or another supported provider). 3. Select the repository that contains (or will contain) your documentation. 4. Choose the branch to deploy (typically `main` or `master`). After the connection, pushes to the configured branch trigger an automatic build and deployment. ### 2\. Clone and open in your editor Clone your docs repository locally: ``` git clone https://github.com/your-org/docs.git cd docs ``` Open the folder in your editor: - **VS Code**: `code .` or use **File → Open Folder** - **Cursor**: `cursor .` or drag the folder into the app ## Project structure and navigation Documentation.AI reads your `.mdx` files and `documentation.json` to generate your site. A typical structure: ``` docs/ ├── documentation.json # Site configuration and navigation ├── getting-started/ │ ├── introduction.mdx │ └── quickstart.mdx ├── api/ │ ├── authentication.mdx │ └── openapi.yaml # Optional OpenAPI for API docs └── guides/ └── integrations.mdx ``` ### File and folder naming guidelines To keep your docs maintainable: - Use **lowercase-with-hyphens** for filenames and directories - `api-authentication.mdx` instead of `APIAuthentication.mdx` - Keep a **shallow structure** where possible - Prefer `guides/integrations.mdx` over deeply nested trees - Match **directory structure to navigation groups** - For example, a `getting-started/` folder for “Getting Started” pages - Use **one main concept per page** - Avoid very long “miscellaneous” pages ### `documentation.json` basics The `documentation.json` file controls: - Sidebar navigation (groups, pages, and their order) - Icons and labels in navigation - Some site-wide configuration and metadata A minimal example of adding a new page: ``` { "tabs": [ { "tab": "Documentation", "groups": [ { "group": "Getting Started", "pages": [ { "title": "Introduction", "path": "getting-started/introduction" }, { "title": "Quickstart", "path": "getting-started/quickstart" } ] } ] } ] } ``` Best practices: - Keep `path` values aligned with your file tree (for example, `getting-started/introduction` → `getting-started/introduction.mdx`). - Prefer **absolute paths from the docs root** for internal links (for example, `[Quickstart](/getting-started/quickstart)`). - Update `documentation.json` when you add, rename, or remove pages so navigation stays in sync. For more advanced organization patterns, see the broader [Organize](/content/docs/organize/overview/index.html) docs. ## Writing docs in MDX ### MDX fundamentals Each page is an `.mdx` file with frontmatter and content: ```markdown --- title: API Authentication description: Learn how to authenticate with our API --- ## API authentication Authenticate using a bearer token in the `Authorization` header. ```bash curl https://api.example.com/data \ -H "Authorization: Bearer $TOKEN" ``` ``` Guidelines: - Always include at least `title` and `description` in frontmatter. - Use markdown for headings, text, lists, and tables. - Use MDX components (JSX-style tags) for richer patterns like callouts, steps, and parameter tables. ### Using Documentation.AI components Documentation.AI ships a set of MDX components tailored for docs. Common examples: ``` Tokens expire after 24 hours; refresh them using the `/auth/refresh` endpoint. Unique identifier for the user ``` For grouped or multi-step content: ``` Go to your account settings, then create a new token with read access. Store the token in an environment variable such as `API_TOKEN`. ``` For code in multiple languages: ````markdown ```javascript const user = await getUser(userId) ``` ```python user = get_user(user_id) ``` ```` Component references: - [Headings and Text](/content/docs/components/heading-and-text/index.html) - [Code and Groups](/content/docs/components/code-blocks-and-groups/index.html) - [Callout](/content/docs/components/callout/index.html) ### Internal links Use absolute paths from the docs root: - ✅ `[Quickstart](/getting-started/quickstart)` - ✅ `[Web Editor](/write-and-publish/web-editor)` - ❌ `../getting-started/quickstart` (relative paths are harder to maintain) This keeps links stable even if you move files or change navigation groups. ### Images, video, and files Media files are not committed to the repository. Upload them to the documentation's [media library](/content/docs/write-and-publish/media-library#code-editor-git/index.html) from the dashboard, copy the CDN URL, and reference it in MDX: ``` Dashboard overview