Navigation Setup

The navigation system is how users browse your documentation. This guide explains how to set it up in config.json.

Understanding Navigation Structure

Your navigation has three levels:

Tabs (top bar)
└── Groups (sidebar sections)
    └── Pages (individual documents)

Think of it like organizing books:

Tabs are like different bookcases ("Documentation", "API", "Guides")
Groups are like shelves in a bookcase ("Getting Started", "Advanced Topics")
Pages are like individual books on a shelf

Basic Navigation Example

Here's a simple navigation setup explained line by line:

config.json

{
"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "icon": "rocket",
          "pages": [
            "guides/introduction",
            "guides/installation"
          ]
        }
      ]
    }
  ]
}
}

What this creates:

A tab called "Documentation" in the top navigation
A group called "Getting Started" in the sidebar (with a rocket icon)
Two pages in that group: Introduction and Installation

Step-by-Step: Adding Pages

Create your MDX file

First, create your documentation file in the /docs folder:

/docs
  /guides
    my-guide.mdx

Add page path to config.json

Add the page path to the pages array in config.json:

json

{
  "pages": [
    "guides/my-guide"
  ]
}

Important rules:

✅ Start from inside /docs (don't include /docs/ in the path)
✅ No .mdx file extension
✅ Use forward slashes / even on Windows
❌ Don't use backslashes \

Save and check

Save config.json and check your browser. The page should appear in the sidebar!

If it doesn't appear, check the terminal for errors.

Navigation Properties

Tabs

Tabs appear in the top navigation bar. Each tab can have its own set of groups and pages.

tab

string

required

The display name for the tab

json

{
  "tab": "Documentation"
}

href

string

Optional external URL (for tabs that link to external sites)

json

{
  "tab": "GitHub",
  "href": "https://github.com/your-repo"
}

groups

array

Array of groups within this tab (only for internal tabs, not external ones)

Example with multiple tabs:

config.json

{
"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [...]
    },
    {
      "tab": "API Reference",
      "groups": [...]
    },
    {
      "tab": "GitHub",
      "href": "https://github.com/example"
    }
  ]
}
}

Groups

Groups organize pages into sections in the sidebar.

group

string

required

The display name for the group

json

{
  "group": "Getting Started"
}

icon

string

Lucide icon name to display next to the group name

json

{
  "group": "Getting Started",
  "icon": "rocket"
}

Popular icons:

rocket - Getting started
settings - Configuration
code - Code/API docs
book - Guides/tutorials
component - UI components
zap - Quick start
shield - Security
database - Data/storage

See all icons: lucide.dev/icons

pages

array

required

Array of page paths

json

{
  "group": "Getting Started",
  "icon": "rocket",
  "pages": [
    "guides/introduction",
    "guides/installation",
    "guides/quick-start"
  ]
}

Pages

Pages are the file paths to your MDX documents.

Path format:

Content file:     /docs/guides/my-guide.mdx
Navigation path:  "guides/my-guide"
URL:              /guides/my-guide/

Complete Example

Here's a realistic navigation setup with multiple tabs and groups:

config.json

{
"navigation": {
  "global": {
    "anchors": [
      {
        "anchor": "GitHub",
        "href": "https://github.com/your-repo",
        "icon": "github"
      },
      {
        "anchor": "Discord",
        "href": "https://discord.gg/your-server",
        "icon": "message-circle"
      }
    ]
  },
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "icon": "rocket",
          "pages": [
            "guides/introduction",
            "guides/installation",
            "guides/quick-start"
          ]
        },
        {
          "group": "Guides",
          "icon": "book",
          "pages": [
            "guides/configuration",
            "guides/customization",
            "guides/deployment"
          ]
        },
        {
          "group": "Advanced",
          "icon": "code",
          "pages": [
            "guides/advanced/api-integration",
            "guides/advanced/custom-components"
          ]
        }
      ]
    },
    {
      "tab": "Components",
      "groups": [
        {
          "group": "UI Components",
          "icon": "component",
          "pages": [
            "components/alert",
            "components/accordion",
            "components/tabs"
          ]
        }
      ]
    },
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Endpoints",
          "icon": "zap",
          "pages": [
            "api/authentication",
            "api/users",
            "api/posts"
          ]
        }
      ]
    }
  ]
}
}

Global Anchors

Global anchors appear above all tabs in the sidebar. Use them for external links like GitHub, Discord, or community resources.

json

{
  "navigation": {
    "global": {
      "anchors": [
        {
          "anchor": "GitHub",
          "href": "https://github.com/your-repo",
          "icon": "github"
        }
      ]
    }
  }
}

anchor

string

required

Display text for the link

href

string

required

URL (can be external or internal)

icon

string

Lucide icon name

Common Patterns

Documentation + Components

A common setup for documentation sites with component examples:

config.json

{
"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "icon": "rocket",
          "pages": ["guides/introduction", "guides/installation"]
        },
        {
          "group": "Guides",
          "icon": "book",
          "pages": ["guides/basics", "guides/advanced"]
        }
      ]
    },
    {
      "tab": "Components",
      "groups": [
        {
          "group": "UI Components",
          "icon": "component",
          "pages": ["components/button", "components/card"]
        }
      ]
    }
  ]
}
}

API Documentation

For API documentation with versioning:

config.json

{
"navigation": {
  "tabs": [
    {
      "tab": "Guides",
      "groups": [
        {
          "group": "Getting Started",
          "icon": "rocket",
          "pages": ["guides/authentication", "guides/quickstart"]
        }
      ]
    },
    {
      "tab": "API v2",
      "groups": [
        {
          "group": "Endpoints",
          "icon": "zap",
          "pages": ["api/v2/users", "api/v2/posts"]
        }
      ]
    },
    {
      "tab": "API v1",
      "groups": [
        {
          "group": "Endpoints",
          "icon": "code",
          "pages": ["api/v1/users", "api/v1/posts"]
        }
      ]
    }
  ]
}
}

Page Ordering

Pages appear in the sidebar in the order you list them in the pages array:

json

{
  "pages": [
    "guides/step-1",  // Appears first
    "guides/step-2",  // Appears second
    "guides/step-3"   // Appears third
  ]
}

To reorder: Just rearrange the items in the array.

Troubleshooting

Page doesn't appear in sidebar

Navigation looks broken

Tab doesn't show up

Best Practices

Don't go more than 3 levels deep (Tab → Group → Page). Users get lost in deep navigation.

Keep it shallow

"Getting Started" is better than "Intro". "API Reference" is better than "API".

Use descriptive names

Put related pages together. Think about the user's learning journey.

Group logically

3-5 tabs maximum. Too many tabs overwhelm users.

Limit tabs

Next Steps

Colors & Theming

Customize your site's colors and theme

Typography

Configure fonts for your documentation

Banner

Add announcement banners to your site

The navigation system is how users browse your documentation. This guide explains how to set it up in config.json.

Understanding Navigation Structure

Your navigation has three levels:

Tabs (top bar)
└── Groups (sidebar sections)
    └── Pages (individual documents)

Think of it like organizing books:

Tabs are like different bookcases ("Documentation", "API", "Guides")
Groups are like shelves in a bookcase ("Getting Started", "Advanced Topics")
Pages are like individual books on a shelf

Basic Navigation Example

Here's a simple navigation setup explained line by line:

config.json

{
"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "icon": "rocket",
          "pages": [
            "guides/introduction",
            "guides/installation"
          ]
        }
      ]
    }
  ]
}
}

What this creates:

A tab called "Documentation" in the top navigation
A group called "Getting Started" in the sidebar (with a rocket icon)
Two pages in that group: Introduction and Installation

Step-by-Step: Adding Pages

Create your MDX file

First, create your documentation file in the /docs folder:

/docs
  /guides
    my-guide.mdx

Add page path to config.json

Add the page path to the pages array in config.json:

json

{
  "pages": [
    "guides/my-guide"
  ]
}

Important rules:

✅ Start from inside /docs (don't include /docs/ in the path)
✅ No .mdx file extension
✅ Use forward slashes / even on Windows
❌ Don't use backslashes \

Save and check

Save config.json and check your browser. The page should appear in the sidebar!

If it doesn't appear, check the terminal for errors.

Navigation Properties

Tabs

Tabs appear in the top navigation bar. Each tab can have its own set of groups and pages.

tab

string

required

The display name for the tab

json

{
  "tab": "Documentation"
}

href

string

Optional external URL (for tabs that link to external sites)

json

{
  "tab": "GitHub",
  "href": "https://github.com/your-repo"
}

groups

array

Array of groups within this tab (only for internal tabs, not external ones)

Example with multiple tabs:

config.json

{
"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [...]
    },
    {
      "tab": "API Reference",
      "groups": [...]
    },
    {
      "tab": "GitHub",
      "href": "https://github.com/example"
    }
  ]
}
}

Groups

Groups organize pages into sections in the sidebar.

group

string

required

The display name for the group

json

{
  "group": "Getting Started"
}

icon

string

Lucide icon name to display next to the group name

json

{
  "group": "Getting Started",
  "icon": "rocket"
}

Popular icons:

rocket - Getting started
settings - Configuration
code - Code/API docs
book - Guides/tutorials
component - UI components
zap - Quick start
shield - Security
database - Data/storage

See all icons: lucide.dev/icons

pages

array

required

Array of page paths

json

{
  "group": "Getting Started",
  "icon": "rocket",
  "pages": [
    "guides/introduction",
    "guides/installation",
    "guides/quick-start"
  ]
}

Pages

Pages are the file paths to your MDX documents.

Path format:

Content file:     /docs/guides/my-guide.mdx
Navigation path:  "guides/my-guide"
URL:              /guides/my-guide/

Complete Example

Here's a realistic navigation setup with multiple tabs and groups:

config.json

{
"navigation": {
  "global": {
    "anchors": [
      {
        "anchor": "GitHub",
        "href": "https://github.com/your-repo",
        "icon": "github"
      },
      {
        "anchor": "Discord",
        "href": "https://discord.gg/your-server",
        "icon": "message-circle"
      }
    ]
  },
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "icon": "rocket",
          "pages": [
            "guides/introduction",
            "guides/installation",
            "guides/quick-start"
          ]
        },
        {
          "group": "Guides",
          "icon": "book",
          "pages": [
            "guides/configuration",
            "guides/customization",
            "guides/deployment"
          ]
        },
        {
          "group": "Advanced",
          "icon": "code",
          "pages": [
            "guides/advanced/api-integration",
            "guides/advanced/custom-components"
          ]
        }
      ]
    },
    {
      "tab": "Components",
      "groups": [
        {
          "group": "UI Components",
          "icon": "component",
          "pages": [
            "components/alert",
            "components/accordion",
            "components/tabs"
          ]
        }
      ]
    },
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Endpoints",
          "icon": "zap",
          "pages": [
            "api/authentication",
            "api/users",
            "api/posts"
          ]
        }
      ]
    }
  ]
}
}

Global Anchors

Global anchors appear above all tabs in the sidebar. Use them for external links like GitHub, Discord, or community resources.

json

{
  "navigation": {
    "global": {
      "anchors": [
        {
          "anchor": "GitHub",
          "href": "https://github.com/your-repo",
          "icon": "github"
        }
      ]
    }
  }
}

anchor

string

required

Display text for the link

href

string

required

URL (can be external or internal)

icon

string

Lucide icon name

Common Patterns

Documentation + Components

A common setup for documentation sites with component examples:

config.json

{
"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "icon": "rocket",
          "pages": ["guides/introduction", "guides/installation"]
        },
        {
          "group": "Guides",
          "icon": "book",
          "pages": ["guides/basics", "guides/advanced"]
        }
      ]
    },
    {
      "tab": "Components",
      "groups": [
        {
          "group": "UI Components",
          "icon": "component",
          "pages": ["components/button", "components/card"]
        }
      ]
    }
  ]
}
}

API Documentation

For API documentation with versioning:

config.json

{
"navigation": {
  "tabs": [
    {
      "tab": "Guides",
      "groups": [
        {
          "group": "Getting Started",
          "icon": "rocket",
          "pages": ["guides/authentication", "guides/quickstart"]
        }
      ]
    },
    {
      "tab": "API v2",
      "groups": [
        {
          "group": "Endpoints",
          "icon": "zap",
          "pages": ["api/v2/users", "api/v2/posts"]
        }
      ]
    },
    {
      "tab": "API v1",
      "groups": [
        {
          "group": "Endpoints",
          "icon": "code",
          "pages": ["api/v1/users", "api/v1/posts"]
        }
      ]
    }
  ]
}
}

Page Ordering

Pages appear in the sidebar in the order you list them in the pages array:

json

{
  "pages": [
    "guides/step-1",  // Appears first
    "guides/step-2",  // Appears second
    "guides/step-3"   // Appears third
  ]
}

To reorder: Just rearrange the items in the array.

Troubleshooting

Page doesn't appear in sidebar

Navigation looks broken

Tab doesn't show up

Best Practices

Don't go more than 3 levels deep (Tab → Group → Page). Users get lost in deep navigation.

Keep it shallow

"Getting Started" is better than "Intro". "API Reference" is better than "API".

Use descriptive names

Put related pages together. Think about the user's learning journey.

Group logically

3-5 tabs maximum. Too many tabs overwhelm users.

Limit tabs

Next Steps

Colors & Theming

Customize your site's colors and theme

Typography

Configure fonts for your documentation

Banner

Add announcement banners to your site