When someone opens your docs site, the links in the left column come from the sidebar property in docs.json, not from the folder layout under docs/. You declare groups, page links, and optional nesting explicitly, and docs.page renders that tree in the sidebar.
The sidebar is your site’s navigation model. Each top-level entry is a group with a pages array. Groups can carry an optional label (group), icon, landing link (href), and tab assignment (tab). Each page entry is a link with a title and href, or another nested group with its own pages.
That structure drives three behaviors readers notice:
- Which links appear in the left nav for the current page
- Which nested sections expand to reveal the active page
- Which translation tree loads when the URL includes a locale segment
Field names, types, and defaults live in docs.json: this page explains the model, not every key.
The sidebar property is either a flat array of groups (single-locale sites) or a record keyed by locale (multi-locale sites). In both shapes, each group is an object with a pages array.
A page item is a leaf link:
{ "title": "Introduction", "href": "/" }Groups without a group label still participate in the tree. They render as an unlabeled block of links. Groups with a group string render a section heading above their pages.
See Introduction for how paths under docs/ map to URL segments; sidebar href values should match those public paths.
pages can contain groups as well as links. A nested group behaves like a collapsible section: optional group label, optional href landing page, and its own nested pages.
{
"group": "Getting Started",
"icon": "rocket",
"pages": [
{ "title": "Introduction", "href": "/" },
{ "title": "Write", "href": "/authoring/write" },
{ "title": "Organize", "href": "/authoring/organize" }
]
}When the current page matches a nested group’s href or any link inside it, that section stays expanded. Nested groups can stack several levels deep using the same object shape.
External URLs in href are supported and show an external-link indicator in the sidebar.
Flat array: use when the site has one language. The entire navigation tree is the array:
"sidebar": [
{ "group": "Guide", "pages": [{ "title": "Welcome", "href": "/" }] }
]Locale-keyed record: use when each locale needs its own sidebar tree. Keys are locale codes; default holds the navigation for URLs without a locale prefix:
"sidebar": {
"default": [
{ "group": "Guide", "pages": [{ "title": "Welcome", "href": "/" }] }
],
"fr": [
{ "group": "Guide", "pages": [{ "title": "Bienvenue", "href": "/fr" }] }
]
}docs.page derives the site’s locale list from every key in that record except default. When a reader’s URL starts with a recognized locale segment (for example /fr/...), the matching keyed array replaces default for sidebar rendering. Internal links in a localized tree can omit the locale prefix. docs.page resolves them against the active locale.
See Locales for how locale segments are detected from the path and how the locale switcher uses the same list.
Top-level Tabs partition the site into separate doc areas. Each group can set tab to a tab id so it only appears when that tab is active. Groups without a tab field appear on every tab.
Tab filtering applies to top-level groups after locale resolution. It does not split individual page links inside a group.
The sidebar defines navigation links and grouping. It does not replace Search, Links anchor shortcuts in the sidebar footer, or Navigation buttons at the bottom of each page. Those read sidebar order but have their own configuration surfaces.