Code Editor

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

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 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.
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 docs.

Writing docs in MDX

MDX fundamentals

Each page is an .mdx file with frontmatter and content:

---
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:

<Callout kind="info">

Tokens expire after 24 hours; refresh them using the `/auth/refresh` endpoint.

</Callout>

<ParamField path="userId" param-type="string" required="true">

Unique identifier for the user

</ParamField>

For grouped or multi-step content:

<Steps>
  <Step title="Create an API token" icon="key">

  Go to your account settings, then create a new token with read access.

  </Step>

  <Step title="Add token to your environment" icon="terminal">

  Store the token in an environment variable such as `API_TOKEN`.

  </Step>
</Steps>

For code in multiple languages:

<CodeGroup tabs="JavaScript,Python">
```javascript
const user = await getUser(userId)
```
```python
user = get_user(user_id)
```
</CodeGroup>

Component references:

• Headings and Text
• Code and Groups
• Callout

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.

Git workflow and collaboration

Documentation.AI uses your Git repository as the single source of truth. A typical cycle:

1. Edit content locally in your editor.
2. Commit changes to a branch.
3. Push to your Git provider.
4. Open a pull request (PR).
5. Documentation.AI builds previews for the PR and deploys when merged.

Recommended branch workflow

git checkout main
git pull
git checkout -b add-webhook-docs

git add .
git commit -m "Add webhook setup documentation"

git push origin add-webhook-docs

Git workflow best-practice checklist

Troubleshooting and common issues

If something looks wrong after a change:

• Navigation is missing or out of order

  • Check the corresponding path entries in documentation.json.
  • Make sure filenames and directory names match the path values.

• Page builds but content is broken

  • Look for invalid MDX (for example, unclosed components or unescaped { in prose).
  • Ensure all components use valid props (for example, kind="info" on <Callout>).

• Deployment did not update

  • Confirm that your changes were merged into the configured deployment branch.
  • Verify that the latest commit triggered a build in your Documentation.AI project.

For deeper debugging, see the general Troubleshoot build failures guide.

Summary

Use the code editor workflow when you want Git-based, developer-friendly documentation:

• Write in .mdx using Documentation.AI components.
• Organize files to match navigation, and keep documentation.json in sync.
• Use branches, commits, and PRs to collaborate, with preview builds for each change.
• Let Documentation.AI handle builds and deployments from your main branch.

For teams that prefer WYSIWYG editing or non-Git workflows, pair this with the Web Editor so both technical and non-technical contributors can work where they are most productive.