Navigation

Navigation

nav.yaml is the one file that decides your sidebar. Ordering does not come from file names or from frontmatter; it comes from here.

The shape

space: Staleless
description: Documentation that cannot go stale without saying so.

sections:
  - label: Start here
    icon: 🚀
    items:
      - page: index
      - page: start/quickstart
  - label: Guides
    icon: 📘
    items:
      - page: guides/deploy
        items:
          - page: guides/rollback
      - separator: true
        label: Reference
      - label: Status
        href: https://status.example.com

Top level

spacestring

The project name, shown in the header.

descriptionstring

One sentence. It becomes the site’s meta description.

spacesarray

A switcher, when a company publishes more than one site. Each entry takes label, href, and current: true on the site being served.

sectionsarrayrequired

The sidebar groups, in order.

A section

labelstringrequired

The group heading.

iconstring

One emoji, shown before the label.

itemsarrayrequired

What the group contains.

The four kinds of item

A page. page: is the path under pages/, without the extension.

- page: guides/install

A nested page. Add items: to a page to nest children under it.

- page: guides/deploy
  items:
    - page: guides/rollback

An external link. href must begin with https://, http://, mailto: or tel:.

- label: Status
  href: https://status.example.com

A separator. A rule between items, with an optional label above it.

- separator: true
  label: Reference

Every page must be listed

A page under pages/ that no section names is an orphan, and the orphan rule is an error. The commit is refused.

This is deliberate. A page nothing links to is a page nobody reads, and the common cause is a file somebody forgot to finish.

Tip

To publish a page that should not appear in the sidebar, list it in nav.yaml and set noindex: true, or keep it as a draft. Do not leave it unlisted.

Moving a page

A move is three changes in one branch:

1. the file, to its new path;
2. nav.yaml, to the new path;
3. redirects.yaml, so the old URL still works.

docs_move over MCP does the first. The linter catches the other two: nav-missing-page if the navigation still points at the old path, and redirect-conflict if a published URL was left with nothing behind it.

Rules the navigation must pass

Rule	Severity	What it means
nav-invalid	error	The YAML does not match the schema.
nav-missing-page	error	A section names a page that does not exist.
nav-duplicate	error	The same page is listed twice.
orphan	error	A page exists that no section lists.

Depth

Nesting is supported. Two levels is usually enough, and three is a sign the section should be split. The sidebar will render what you write; the reader has to hold it in their head.