Two navigation modes
CodivDocs supports two ways of organizing your sidebar. Pick whichever matches the shape of your docs — the platform figures out the rest.
Flat groups
A single sidebar with top-level groups. Best for small-to-medium docs sites with one audience.
Tabbed sections
Top-navbar tabs switch the sidebar between independent sections. Best when you have distinct audiences (e.g. Guides vs. API Reference).
Flat groups
The simplest configuration. One sidebar, multiple groups, each group holds a list of pages.
{
"navigation": [
{
"group": "Getting Started",
"pages": [
"docs/introduction",
"docs/quickstart"
]
},
{
"group": "Configuration",
"pages": [
"docs/configuration/config-file",
"docs/configuration/custom-domain"
]
}
]
}The sidebar renders every group in order. Breadcrumbs show the parent group as an eyebrow label above the h1. Prev/next walks the full flat sequence.
Tabbed sections
When you have distinct top-level sections that deserve their own sidebar, wrap each one in a tab:
{
"navigation": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": ["docs/introduction", "docs/quickstart"]
},
{
"group": "Configuration",
"pages": ["docs/configuration/config-file"]
}
]
},
{
"tab": "API Reference",
"groups": [
{
"group": "Endpoints",
"pages": [
"docs/api/authentication",
"docs/api/projects",
"docs/api/deployments"
]
}
]
}
]
}The header renders Documentation and API Reference as tabs in the top navbar. Clicking a tab switches the sidebar to show only that tab's groups. The active tab is detected from the current URL — whichever tab contains the page you are reading gets the primary-color underline.
Tabbed mode is all-or-nothing at the top level. Either every top-level entry is a tab, or every top-level entry is a group. Mixing the two is not supported and will cause only the tabs to render.
Prev/next within tabs
In tabbed mode, prev/next stay inside the current tab. The Next button on the last Documentation page does not jump to the first API Reference page — each tab is a self-contained reading sequence.
In flat mode, prev/next walks the entire navigation as one list.
File path convention
Entries in pages are file paths relative to your repo root, without the .mdx extension. The platform converts them to URL paths automatically:
| Entry | File | URL |
docs/introduction | docs/introduction.mdx | /introduction |
docs/api/auth | docs/api/auth.mdx | /api/auth |
docs/guides/deploy | docs/guides/deploy.mdx | /guides/deploy |
The docs/ prefix is stripped from the URL — it is just a folder organization convention for your repo.
Nested groups
Navigation groups can themselves contain sub-groups for deeper hierarchy:
{
"group": "API Reference",
"pages": [
"docs/api/authentication",
{
"group": "Endpoints",
"pages": [
"docs/api/users/create",
"docs/api/users/list"
]
}
]
}Nested groups render in the same sidebar column (no indentation level limit in the config), but visual indentation in the sidebar is currently capped at two levels. Deeper nesting is preserved in the flattened order for prev/next but visually collapsed.
Full example
A real multi-audience docs config — the CodivDocs dogfood setup uses this exact pattern:
{
"name": "CodivDocs",
"navigation": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": ["docs/introduction", "docs/quickstart", "docs/concepts"]
},
{
"group": "Features",
"pages": [
"docs/features/search",
"docs/features/theme-toggle",
"docs/features/reading-experience",
"docs/features/code-blocks",
"docs/features/copy-for-llms"
]
},
{
"group": "Configuration",
"pages": [
"docs/configuration/config-file",
"docs/configuration/custom-domain",
"docs/configuration/navigation",
"docs/configuration/theme"
]
}
]
},
{
"tab": "Components",
"groups": [
{
"group": "Basics",
"pages": [
"docs/components/callout",
"docs/components/card",
"docs/components/code-group",
"docs/components/tabs",
"docs/components/accordion"
]
},
{
"group": "Layout",
"pages": ["docs/components/steps", "docs/components/frame"]
},
{
"group": "API docs",
"pages": [
"docs/components/param-field",
"docs/components/response-field"
]
}
]
},
{
"tab": "API Reference",
"groups": [
{
"group": "Endpoints",
"pages": [
"docs/api/authentication",
"docs/api/projects",
"docs/api/deployments"
]
}
]
}
]
}