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 your site's icon 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

Long Titles in the Sidebar

By default, a page title or group label too long for the sidebar wraps onto as many lines as it needs, so the full title is always visible. This applies to both templates and to the sidebar menu on phones.

To keep every item on a single line instead, turn off Wrap long titles in the Editor under Site Config > Brand & Theme > Sidebar, then publish. Long titles are then cut off with an ellipsis, and hovering an item shows its full title.

In documentation.json, the same setting is title-wrap in the sidebar object:

{
  "sidebar": {
    "title-wrap": false
  }
}

Omit it, or set it to true, to wrap. See the site configuration reference.

Troubleshooting Navigation Issues

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

Broken icons: Check icon names against your site's icon library, or add the library the icon comes from, such as lucide:rocket

Navigation too deep: Reorganize content into broader categories

Unclear hierarchy: Use more descriptive group and page names

Titles cut off on one line: sidebar.title-wrap is set to false. Turn on Wrap long titles under Site Config > Brand & Theme > Sidebar, or remove the setting, and publish.

What's Next

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