Navigation

Use docs.json to control tabs, sidebar groups, and page order. Start simple, then add structure only if you need it.

Quick start#

Use one tab with one group:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "groups": [
          { "group": "Getting started", "pages": ["index", "installation"] }
        ]
      }
    ]
  }
}

Link tabs#

A tab can link to a URL instead of owning docs pages. Use this to surface a standalone page (or an external site) in the top navigation:

{
  "navigation": {
    "tabs": [
      { "tab": "Docs", "groups": [{ "group": "Start", "pages": ["index"] }] },
      { "tab": "Playground", "icon": "layout-dashboard", "href": "/playground" }
    ]
  }
}

Internal hrefs navigate client-side and highlight the tab when active; external URLs open in a new browser tab. A link tab cannot also define groups, pages, or dropdowns.

When to use each pattern#

• navigation.tabs: best default for most docs sites
• navigation.dropdowns: top-level categories rendered as menus by the Shiso theme
• navigation.groups + navigation.pages: good for a single simple section
• navigation.versions: multiple product versions, each with its own navigation and a version selector in the header; see Versions
• navigation.languages: translated docs, each with its own navigation and a language selector; see Languages

These modes are mutually exclusive: define exactly one of tabs, dropdowns, versions, languages, or top-level groups/pages (which combine into one simple mode). The same rule applies inside each version and language entry. At most one version or language may set default: true; without an explicit default, the first visible entry is used.

Page entries#

Inside pages, you can mix:

String slugs — the file path without extension:

"installation"

Page objects — for custom labels, icons, tags, or hidden pages:

{ "page": "installation", "title": "Install", "icon": "download", "tag": "New" }

• title (or label, which wins): custom sidebar text
• icon: a lucide icon name shown beside the label
• tag: a short badge shown after the label
• hidden: keep the page out of the sidebar and search — it is still built and reachable by URL

Glob entries — include matching Markdown and MDX files automatically:

{
  "pages": [
    "index",
    { "glob": "guides/**", "exclude": ["guides/drafts/**"] }
  ]
}

Patterns are relative to contentDir. * matches within one folder, ** matches across folders, and .md or .mdx extensions are optional. Matches are sorted by order frontmatter and then by file path. Configure an automatically discovered page in its frontmatter:

---
title: Deploy the application
sidebarTitle: Deployment
order: 20
hidden: false
---

sidebarTitle overrides the navigation label, while title remains the page and browser title. If sidebarTitle is absent, the page title is used. hidden: true keeps the generated entry out of visible navigation and search. Explicit page entries take precedence over glob matches, so you can customize a page's label, icon, tag, visibility, or exact position without adding it to exclude. Duplicate explicit entries and overlaps between two globs remain configuration errors. Adding, removing, or editing a matching content file refreshes the generated navigation during development.

External links:

{ "href": "https://github.com/example/repo", "label": "GitHub", "icon": "github" }

Nested groups — arbitrarily deep, with an optional landing page:

{
  "group": "Getting started",
  "root": "index",
  "icon": "rocket",
  "expanded": true,
  "collapsible": false,
  "pages": ["installation", "configuration"]
}

Set collapsible: false to keep a group open without a chevron. Groups also accept hidden, which hides the group and everything in it.

Collapsible groups#

Groups are collapsible and show a chevron by default:

• Top-level groups start expanded
• Nested groups start collapsed unless expanded: true is set or the current page is inside them

Navigating into a group reopens it. The interaction.drilldown key controls what clicking a group header does:

{
  "interaction": { "drilldown": true }
}

• true: expanding a group also navigates to its root (or first) page
• false: the header only expands and collapses
• unset: headers with a root page navigate (title is a link; chevron toggles); others only expand/collapse

Anchors#

Anchors render as prominent links above the sidebar. Each anchor requires both anchor (the label) and href:

{
  "navigation": {
    "anchors": [
      { "anchor": "Community", "href": "https://discord.gg/example", "icon": "users" }
    ],
    "tabs": [
      { "tab": "Docs", "pages": ["index", "installation"] }
    ]
  }
}

Hidden pages#

Any tab, group, page, or link accepts hidden: true. Hidden pages are still prerendered and reachable by URL, but they:

• do not appear in the sidebar
• are skipped by prev/next paging
• are excluded from sitemap.xml and marked noindex (unless seo.indexing is "all")

More examples#

Dropdowns#

{
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Docs",
        "pages": ["index", "configuration"]
      }
    ]
  }
}

Common mistakes#

You will see a config error when:

• navigation is missing
• more than one navigation mode is defined at the same level
• versions or languages is empty, or more than one entry is default: true
• an anchor is missing anchor or href
• no pages are discovered
• a navigation glob matches no files or leaves the content directory
• duplicate page file slugs exist
• duplicate route slugs exist
• referenced docs files do not exist in content/docs

Slug tips#

• .md and .mdx extensions are optional in pages entries
• docs/ prefix is accepted and removed
• trailing /index collapses to the parent route slug
• "index" maps to /docs