Navigation
Configure sidebar groups, tabs, and page ordering in docs.json.
You control the sidebar hierarchy, tabbed sections, and hidden pages through the navigation object in docs.json. This page covers every navigation feature.
Groups organize pages into collapsible sidebar sections. Each group has a label and a list of page slugs.
{
"navigation": {
"groups": [
{
"group": "Getting started",
"pages": ["index", "quickstart"]
},
{
"group": "Guides",
"pages": ["guides/authentication", "guides/deployment"]
}
]
}
}Page slugs map directly to file paths. A slug like domains/custom-domains resolves to domains/custom-domains.mdx in your docs directory.
docs/
domains/
custom-domains.mdx -> slug: "domains/custom-domains"
ssl.mdx -> slug: "domains/ssl"
index.mdx -> slug: "index"
Tabs add top-level sections to your documentation. Each tab contains its own set of groups, creating separate sidebar navigations.
{
"navigation": {
"tabs": [
{
"tab": "Guides",
"groups": [
{ "group": "Getting started", "pages": ["index", "quickstart"] }
]
},
{
"tab": "API reference",
"groups": [
{ "group": "Endpoints", "pages": [
A tab must define at least one of groups, pages, or href.
Use the hidden array to keep pages accessible by URL without showing them in the sidebar. This is useful for deprecated pages, redirects, or unlisted content.
{
"navigation": {
"hidden": ["internal/debug", "legacy/old-api"],
"groups": [{ "group": "Guides", "pages": ["index", "quickstart"] }]
}
}You can generate API reference pages directly from an OpenAPI spec by adding an openapi field to a group instead of listing pages manually.
{
"group": "API reference",
"openapi": "openapi.yaml"
}For large projects, you can split your navigation into separate JSON files using $ref. This keeps your main docs.json manageable.
{
"navigation": {
"tabs": [{ "$ref": "./nav/guides.json" }, { "$ref": "./nav/api.json" }]
}
}{
"tab": "Guides",
"groups": [{ "group": "Getting started", "pages": ["index", "quickstart"] }]
}Version dropdowns let you maintain multiple documentation versions from a single project.
{
"navigation": {
"versions": [
{ "label": "v2.0", "url": "/v2" },
{ "label": "v1.0", "url": "/v1" }
],
"groups": [...]
}
}Language selectors let you link to translated versions of your documentation.
{
"navigation": {
"languages": [
{ "label": "English", "url": "/en" },
{ "label": "Japanese", "url": "/ja", "locale": "ja" }
],
"groups": [...]
}
}Global anchors appear as persistent links in the navigation, visible across all tabs. Use them for external resources like your dashboard, community, or changelog.
{
"navigation": {
"global": {
"anchors": [
{ "label": "Community", "href": "https://discord.gg/example" },
{ "label": "Dashboard", "href": "https://app.example.com" }
],
"links": [
{ "label": "Blog", "href": "https://blog.example.com" }
]
},
The full navigation object supports all of the following fields:
Your navigation must define at least one of groups, pages, tabs,
languages, or versions.
languages |
| Array<{ label, url, locale? }> |
| Language selector entries. |
| Yes |
global | { anchors?, links? } | Global anchors and links visible across all tabs. | Yes |