# Set Up Navigation and Sidebar

Create an organized navigation structure for your documentation site using the optimal hierarchy for your content and users.

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](https://lucide.dev/icons/)

### Step 2: Configure simple page navigation

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

```json
{
  "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:

- **title** (string) - Required, Display name shown in navigation and browser title.
- **path** (string) - Relative path to your MDX file. Specify the path without the `.mdx` extension.
- **icon** (string) - Page icon from the Lucide React icon library.
- **href** (string) - External URL for links that open in new tabs. Use instead of `path` for external links.

### Step 4: Set up groups for larger sites

For organized sections, use groups:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](https://lucide.dev/icons/)

**Navigation too deep**: Reorganize content into broader categories

**Unclear hierarchy**: Use more descriptive group and page names

## What's Next

- [Customize your site branding](/content/docs/customize/branding/index.html)
- [Set up header and navbar elements](/content/docs/customize/header-and-navbar/index.html)
- [Configure colors and typography](/content/docs/customize/colors-and-typography/index.html)
- [See complete site configuration reference](/content/docs/customize/site-configuration/index.html)

Navigation configuration is completely flexible. You can mix and match structures as your content grows. Start simple and add complexity only as needed for better user experience.