Code Editor - Documentation.AI

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:

If you prefer visual editing, real-time collaboration, and publishing without Git, see the Web Editor.

When to use the code editor workflow

Choose the code editor workflow when you want:

Use the Web Editor when you need:

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:

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:

documentation.json basics

The documentation.json file controls:

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:

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:

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

Unique identifier for the user

 ```

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:

Internal links

Use absolute paths from the docs root:

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 from the dashboard, copy the CDN URL, and reference it in MDX:

<Image src="https://blob-cdn.documentation.ai/org-.../doc-.../1757300000000-abc123-overview.png" alt="Dashboard overview" />

<Video src="https://video-cdn.documentation.ai/org-.../doc-.../1757300000000-abc123-walkthrough.mp4" poster="https://blob-cdn.documentation.ai/org-.../doc-.../1757300000000-abc123-walkthrough-poster.jpg" render-type="video" />

[Download the API reference (PDF)](https://file-cdn.documentation.ai/org-.../doc-.../1757300000000-abc123-api-reference.pdf)

Replacing a file in the library keeps its URL, so pages update without a commit. See Images, Videos and iframes, and Files for props.

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

Create a feature branch

Start from your main branch:

git checkout main

git pull
git checkout -b add-webhook-docs

Use descriptive branch names such as fix-typos-billing-page or add-api-errors-doc.

Edit and preview locally

Commit with clear messages

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

Keep commits focused on related changes to make reviews easier.

Push and open a PR

git push origin add-webhook-docs

Then open a pull request in your Git provider. Documentation.AI automatically builds a preview for the PR so reviewers can see the rendered docs.

Review and merge

Documentation.AI then runs a production build and publishes changes.

Git workflow best-practice checklist

Before you open a pull request

During review

After merge

Use feature branches and PRs even for documentation-only changes. Documentation.AI generates preview builds for pull requests, which helps reviewers catch structural or navigation issues before they reach production.

Troubleshooting and common issues

If something looks wrong after a change:

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

Summary

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

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.