Navigation

The sidebar, breadcrumb, and prev/next chrome all derive from a navigation graph built at startup by walking content/docs/**. You control ordering with meta.json; presence is automatic.

The core rule

Files decide presence, meta.json decides order.

Drop a .md into a folder, it shows up. meta.json lists the slugs you want to control ordering for; anything not listed appears alphabetically after your explicit list.

Basic meta.json

Each folder can carry a meta.json:

{
  "title": "Getting Started",
  "pages": ["installation", "quick-start", "project-structure", "configuration"]
}

Slug entries

A slug is a file basename without .md, or a subfolder name : both resolve the same way.

{ "pages": ["introduction", "getting-started", "components"] }

• "introduction" → content/docs/introduction.md
• "getting-started" → content/docs/getting-started/ (subfolder becomes a section)
  Don't give a page and a folder the same name in one directory. For a landing page at a folder's URL, put an index.md inside the folder.

Dividers

The literal string "---" becomes a section divider in the sidebar : a thin rule with no click affordance.

{
  "pages": [
    "introduction",
    "---",
    "getting-started",
    "---",
    "components",
    "cli"
  ]
}

Use dividers to group related pages without wrapping them in a nested section.

Subsections

An object entry with title and pages renders a nested labeled group without needing a real subfolder. Handy when the content lives under a flat structure but you want visual grouping.

{
  "pages": [
    "introduction",
    {
      "title": "Guides",
      "pages": ["installation", "quick-start"]
    },
    {
      "title": "Reference",
      "pages": ["components", "cli", "tokens"]
    }
  ]
}

Subsection pages still resolve at their normal URLs : the subsection is a sidebar-only construct.

Auto-append

Files or folders not listed in a meta.json are appended alphabetically after your explicit list. So dropping a new .md into content/docs/components/ shows it in the sidebar without editing meta.json.

Auto-append order

Within the auto-appended group:

1. Subfolders first, alphabetically by folder name.
2. Pages after, ordered by frontmatter order (ascending), then alphabetically by title as a tie-breaker.

Set order: N in a page's frontmatter to control its position within the auto-appended group.

No meta.json

If a folder has no meta.json, everything auto-orders:

1. Subfolders first, alphabetically.
2. Pages after, order then alphabetical.

Hidden pages

hidden lists slugs (page or folder) that should route but not appear in the sidebar. Their URLs still resolve, and their content is still indexed by search : they just don't show up in navigation.

{
  "pages": ["introduction", "getting-started"],
  "hidden": ["landing", "archived"]
}

Use cases:

• Landing pages reached only through the package selector
• Private drafts in-flight
• Archived content kept for URL stability

Hidden folder children are still indexed : the framework walks the tree and stores every URL, so deep links work.

URLs

Index pages

An index.md in a folder is that folder's landing page. In the sidebar the section label links to it and is highlighted when it is the current page; the page is not listed a second time underneath. In a collapsible section the chevron is a separate button, so the label can be a link.

List it first in the folder's meta.json, or leave it out and let it sort by order:

{ "title": "Authoring", "pages": ["index", "frontmatter", "fenced-code"] }

Folder URLs redirect

A folder with no index.md has no page of its own. Visiting its URL redirects to the first page inside it, so /docs/components goes to /docs/components/callout and /docs goes to the first page of the docs. Details and custom rules are in Redirects.

title on a subfolder

Set title in the folder's meta.json to control the sidebar section header. It falls back to a title-cased folder name, which is wrong for acronyms: a cli folder becomes "Cli". Set "title": "CLI" for those.

Versions

When docs versions are configured, the sidebar shows only the current version's pages, and prev/next and search stay inside it. See Versioning.

See also