Navigation basics

navigation lists your pages and how they’re organized. Its simplest form is an array: one sidebar, shared by every page. Each item in it is a page, a group or a link.

{
  "navigation": [
    "index",
    {
      "group": "Get started",
      "pages": ["docs/quickstart", "docs/installation"]
    },
    {
      "group": "Guides",
      "page": "docs/guides",
      "pages": [
        "docs/guides/webhooks",
        { "group": "Advanced", "pages": ["docs/guides/retries", "docs/guides/idempotency"] }
      ]
    },
    { "label": "Status", "href": "https://status.example.com" }
  ]
}

For tabs, versions, languages or products - more than one sidebar - see Tabs, versions, languages and products.

Pages

A page is its id: its path from the project folder, without the extension. "docs/guides/webhooks" is docs/guides/webhooks.mdx, and "about" is about.mdx at the project root. See Project structure.

In the sidebar, a page shows its sidebarTitle, or its title, along with the icon, tag and Deprecated label its frontmatter sets - see Frontmatter.

A page listed in the navigation that doesn’t exist is an error in writedocs validate, with its line in writedocs.json.

Groups

A group is a heading with pages under it:

group string required

The group’s name.

pages array required

Its pages, groups and links, in order.

page string

A page for the group itself - an overview of what’s in it. The group’s name becomes a link to it.

openapi object

In place of pages: an OpenAPI spec, with a page generated for each of its operations. See API reference.

Groups nest to any depth. A top-level group is a heading in the sidebar, with space around it so each group reads as its own block; a group inside another group is a row that opens and closes, and starts open when the page being read is in it.

A group with page has two parts: its name opens the page, and the arrow next to it opens and closes the group.

Links

A link to another site, in the sidebar next to pages and groups:

label string required

The text shown.

href string required

Where it goes. A link to another site opens in a new tab.

{ "label": "Community forum", "href": "https://forum.example.com" }

To make a page’s sidebar entry a link instead, set url in its frontmatter - see Frontmatter.

Order, previous and next

The order in navigation is the order of the sidebar, and of the Previous and Next links at the bottom of each page. To reorder both, reorder navigation.

A page can leave out those links with hideFooterPagination: true in its frontmatter.

Breadcrumbs

A page in a group shows a trail above its title: a home icon, then each group it’s in, from the outermost. A group with its own page is a link to it. A page at the top level of the navigation, in no group, has no trail.

A page that isn’t in navigation is still built at its address - a page linked from elsewhere, or a landing page. It has no sidebar: it’s laid out like mode: frame, unless its frontmatter sets another mode. To keep a page listed in the navigation but out of the sidebar, set hidden: true in its frontmatter.

To give a tab, dropdown or product an overview page that opens when it’s chosen, use its page - see An item’s own page.