logo
Code EditorOrganize
Code Editor

Organize Content Structure

Structure documentation files and configure navigation in Documentation.AI using code editors

Organize Content Structure

Organize documentation files and configure site navigation when working with code editors. Use documentation.json to control how your content appears in the published documentation.

File Organization

Documentation Structure

Organize files to match your site's navigation:

docs/
├── documentation.json       # Navigation and site config
├── getting-started/
│   ├── introduction.mdx
│   └── quickstart.mdx
├── api/
│   ├── authentication.mdx
│   └── openapi.yaml
└── guides/
    └── integration.mdx

Naming Guidelines

  • Lowercase with hyphens: api-authentication.mdx
  • Descriptive paths: Match your navigation structure
  • No spaces: Use hyphens instead of spaces
  • Consistent depth: Keep similar content at the same directory level

Navigation Configuration

Configure site navigation in documentation.json. The navigation structure controls how pages appear in your sidebar.

Basic Navigation

{
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "icon": "rocket",
        "pages": [
          {
            "title": "Introduction", 
            "path": "getting-started/introduction"
          },
          {
            "title": "Quickstart",
            "path": "getting-started/quickstart"
          }
        ]
      },
      {
        "group": "API Reference",
        "icon": "code", 
        "openapi": "api/openapi.yaml",
        "pages": [
          {
            "title": "Authentication",
            "path": "api/authentication"
          }
        ]
      }
    ]
  }
}

Nested Navigation

Create nested groups for complex hierarchies:

{
  "navigation": {
    "groups": [
      {
        "group": "Guides",
        "pages": [
          {
            "title": "Overview", 
            "path": "guides/overview"
          },
          {
            "group": "Integrations",
            "expandable": true,
            "pages": [
              {
                "title": "Webhooks",
                "path": "guides/webhooks"
              },
              {
                "title": "Third-party Tools", 
                "path": "guides/third-party"
              }
            ]
          }
        ]
      }
    ]
  }
}

Tab-based Navigation

Separate major sections with tabs:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "icon": "book",
        "groups": [
          {
            "group": "Getting Started",
            "pages": [
              {"title": "Introduction", "path": "intro"}
            ]
          }
        ]
      },
      {
        "tab": "API Reference", 
        "icon": "code",
        "openapi": "api/openapi.yaml"
      }
    ]
  }
}

Page Configuration

Front Matter Setup

Add metadata to each MDX file:

---
title: API Authentication
description: Learn how to authenticate with our API using JWT tokens
---

SEO Enhancement

Add structured data for better search results:

---
title: Webhook Integration Guide
description: Step-by-step guide to setting up webhooks
ogImage: https://your-cdn.com/webhook-guide.png
jsonLd:
  "@context": "https://schema.org"
  "@type": "HowTo"
  "name": "Setting Up Webhooks"
---

See page configuration reference for all options.

AI Assistant Users: If you're using Cursor, Windsurf, or similar AI coding agents, use our configuration prompts to help generate proper documentation.json navigation structures and page configurations.

Content Management

Internal Links

Link between pages using relative paths:

See the [API authentication guide](../api/authentication) for setup.

For troubleshooting, check our [support guide](../support/faqs).

Cross-references

Same directory: [Quickstart](quickstart)
Parent directory: [Introduction](../getting-started/introduction)
Sibling directory: [API Auth](../api/authentication)

External Resources

Link to external sites with full URLs:

[GitHub Repository](https://github.com/company/repo)
[Status Page](https://status.example.com)

Editor Organization

VS Code Configuration

Optimize VS Code for documentation work:

// .vscode/settings.json
{
  "files.associations": {
    "*.mdx": "markdown"
  },
  "markdown.preview.breaks": true,
  "cSpell.words": [
    "Documentation", 
    "OpenAPI",
    "webhook"
  ]
}

Cursor AI Features

  • Content suggestions - AI helps with documentation structure
  • Smart completion - Auto-complete for component syntax
  • File organization - AI suggests logical file placement

Navigation Tips

Quick file access: Ctrl+P / Cmd+P
Symbol navigation: Ctrl+Shift+O / Cmd+Shift+O
Multi-file search: Ctrl+Shift+F / Cmd+Shift+F

Best Practices

Maintainable Structure

  • Shallow nesting - Keep directories 2-3 levels maximum
  • Consistent naming - Use the same patterns across sections
  • Logical grouping - Group related content together
  • Clear hierarchy - Structure matches your navigation

Validation

Regularly check your organization:

  • Path accuracy - All navigation paths reference existing files
  • Link validation - Internal links resolve correctly
  • Front matter - All pages have required metadata
  • Navigation sync - File structure matches documentation.json

Team Collaboration

For team workflows:

  • Assign sections to team members
  • Use feature branches for major structural changes
  • Review navigation updates in pull requests
  • Keep documentation.json conflicts to minimum

Next Steps

Powered by Documentation.AI