Set Up Navigation and Sidebar

Create a well-organized navigation structure for your documentation site. The Documentation.AI platform offers multiple navigation patterns - choose the one that best fits your content structure and user needs.

Prerequisites

• Your content structure planned out
• List of your documentation pages and their organization
• Access to your documentation.json file
• Understanding of your user navigation patterns

Choose Your Navigation Pattern

Select the structure that matches your content complexity:

• Pages: Simple flat list (5-10 pages)
• Groups: Section-based organization (10-50 pages)
• Tabs: Multiple product areas (50+ pages)
• Menus: Complex hierarchical structure
• Versions: Multiple product versions
• Dropdowns: Very complex sites with multiple sections

Set Up Basic Navigation

Step 1: Plan your content structure

Before configuring navigation, organize your content:

1. List all your documentation pages (each should be an MDX file)
2. Group related topics together
3. Determine logical user paths through your content
4. Choose appropriate icons from the Lucide React library

Step 2: Configure simple page navigation

For sites with fewer than 10 pages, use a simple pages structure:

{
  "navigation": {
    "pages": [
      {
        "title": "Introduction",
        "path": "getting-started/introduction",
        "icon": "star"
      },
      {
        "title": "API Reference",
        "path": "api/overview", 
        "icon": "code"
      }
    ]
  }
}

Step 3: Add page properties

For each page in your navigation, configure:

Step 4: Set up groups for larger sites

For organized sections, use groups:

{
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "icon": "rocket",
        "expandable": false,
        "pages": [
          {
            "title": "Introduction",
            "path": "getting-started/introduction"
          }
        ]
      }
    ]
  }
}

Advanced Navigation Setup

Step 5: Add tabbed navigation

For multiple product areas or distinct sections:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation", 
        "icon": "book",
        "groups": [
          {
            "group": "Getting Started",
            "pages": [
              {
                "title": "Introduction",
                "path": "docs/introduction"
              }
            ]
          }
        ]
      }
    ]
  }
}

Step 6: Configure expandable groups

Control which sections can collapse:

{
  "group": "Advanced Topics",
  "expandable": true,
  "pages": [...]
}

Set expandable: false for sections you want always visible.

Step 7: Add external links

Include links to external resources:

{
  "title": "GitHub Repository",
  "href": "https://github.com/your-org/repo", 
  "icon": "github"
}

Add API Documentation

Step 8: Integrate OpenAPI specs

For automatic API documentation generation:

{
  "group": "API Reference",
  "openapi": "api/openapi.json",
  "pages": [
    {
      "title": "Authentication",
      "path": "api/authentication"
    }
  ]
}

The openapi property accepts:

• JSON files (.json)
• YAML files (.yaml, .yml)
• Relative paths within your project

Test Your Navigation

Step 9: Verify navigation structure

1. Save your documentation.json file
2. Deploy or preview your site
3. Test all navigation links work correctly
4. Verify page titles display properly
5. Check that expandable groups function as expected
6. Test external links open correctly

Step 10: Optimize user experience

• Keep navigation depth under 3 levels
• Use clear, descriptive page titles
• Group related content logically
• Add icons to improve visual scanning
• Test navigation on mobile devices

Troubleshooting Navigation Issues

Missing pages: Verify file paths match your MDX files (without .mdx extension)

Broken icons: Check icon names against the Lucide React library

Navigation too deep: Reorganize content into broader categories

Unclear hierarchy: Use more descriptive group and page names

What's Next

• Customize your site branding
• Set up header and navbar elements
• Configure colors and typography
• See complete site configuration reference