Navigation

Navigation in docs-builder is defined through the toc: section in your docset.yml or in separate toc.yml files. The table of contents controls which pages appear in the sidebar and in what order.

For the complete reference of all toc: keys, see the docset.yml reference.

toc:
  - file: index.md
  - file: getting-started.md
  - folder: guides
    children:
      - file: index.md
      - file: quickstart.md
		

By default, the sidebar uses the page's # Heading. To show a shorter label, add navigation_title frontmatter:

---
navigation_title: Quick start
---

# Getting started with docs-builder in 5 minutes
		

For larger documentation sets, split navigation into separate toc.yml files:

# docset.yml
toc:
  - file: index.md
  - toc: guides
  - toc: reference
		

# guides/toc.yml
toc:
  - file: index.md
  - file: quickstart.md
		

toc:
  - file: index.md
  - file: getting-started.md
  - file: api-reference.md
		

Group related sibling files under a parent without creating a folder:

toc:
  - file: getting-started.md
    children:
      - file: installation.md
      - file: configuration.md
		

All children must be siblings of the parent file (same directory).

Auto-include all markdown files in a folder. Useful during development:

toc:
  - folder: api
		

Define exact files and ordering:

toc:
  - folder: api
    children:
      - file: index.md
      - file: authentication.md
      - file: endpoints.md
		

When children is defined, all markdown files in the folder must be listed.

A file entry without children that points at an index.md inside a subdirectory is treated as a single-page subsection for that directory:

toc:
  - file: reference/1password/index.md
  - file: reference/activemq/index.md
		

Each entry becomes its own subsection linking to the directory's index.md. This is shorthand for the explicit folder: + file: form, which remains the preferred approach for folders that also have additional children:

toc:
  - folder: reference/1password
    file: index.md
  - folder: reference/activemq
    file: index.md
		

The shorthand also works inside a parent folder's children list, which is the common case for a directory of single-page subsections (for example, dozens of integrations under reference):

toc:
  - folder: reference
    file: index.md
    children:
      - file: 1password/index.md
      - file: activemq/index.md
		

Each child becomes its own subsection; none is consumed as the parent's index page.

If the entry declares its own children, it keeps the virtual grouping behavior instead.

Include a dedicated toc.yml for large sections:

toc:
  - file: index.md
  - toc: api-reference
  - toc: tutorials
		

Combine patterns as needed:

toc:
  - file: index.md
  - file: quick-start.md
  - folder: guides
    children:
      - file: index.md
      - file: installation.md
  - toc: api-reference
  - folder: troubleshooting