Navigation lives under the navigation key in docs.json. Pages are referenced by their file path without the extension (getting-started/install → getting-started/install.mdx).
Groups
The simplest form is a sidebar of grouped pages, nestable to any depth:
Group options:
icon and tag decorate the group heading.root makes the group title itself a link to a page. With interaction.drilldown: false in docs.json, clicking the title toggles the group instead of navigating.expanded: true opens a nested group by default (nested groups start collapsed).hidden: true removes an item from the sidebar and the sitemap. The page is still built, reachable by URL, and searchable; to also exclude it from search and mark it noindex, set hidden: true in the page’s own frontmatter.directory: "accordion" or "card" renders an automatic listing of the group’s children on its root page.
Tabs
Split the site into top-level sections, each with its own sidebar:
A tab with href is an external link. A tab (or any navigation element) with an openapi source and no explicit pages auto-populates from the spec. See API references.
Anchors, dropdowns, and products
anchors render as a link list at the top of the sidebar; dropdowns and products render as a selector. All take the same shape as tabs: a label, an optional icon, and either nested navigation or an href.
Use one navigation kind per level, for example tabs at the top level and groups inside each tab. If several kinds appear at the same level, a fixed priority picks one (tabs, then anchors, dropdowns, products, versions, languages) and a sibling groups array is dropped.
A tab can also carry a menu: its entries flatten into the sidebar as always-expanded groups, or as external links when they have an href. The selector kinds (dropdowns, products, versions, languages) render only when at least two visible entries exist.
versions and languages are also accepted and render as selectors, but content is not scoped per version or language; pages are shared across all of them. Avoid building on these for now.
Global anchors
Links shown across every tab and section:
Only global.anchors is supported, and each entry needs an href.
External links as pages
A page entry can also be declared in frontmatter as an external link: give the MDX file a url frontmatter field and it becomes a sidebar link without a generated page.
Search ranking
Add boost to any group or page entry (or boost in page frontmatter) to weight it in search results. The value is inherited down the navigation tree; frontmatter wins over navigation.
Home page and pagination
- If no page maps to
/, visitors are redirected to the first page of the navigation.
- Pages in
default and frame modes get previous/next pagination within their section, unless disabled per page with hideFooterPagination.
