Authoring

Navigation model

How the sidebar, pager, and home listing decide what to show.

Five rules cover 100% of the theme’s navigation behavior. Once you know them, you can predict exactly where any page will appear.

Rule 1 — Order is by weight, then title #

Every list (sidebar, pager, card grid, search index) is sorted ascending by weight. Pages with the same weight are sorted by title next, then by file path.

The convention used throughout the theme is weight = 10, 20, 30, … so you can insert pages without renumbering.

Rule 2 — hidden: true excludes the page from listings #

When a page has hidden: true in front matter:

• Sidebar: page doesn’t appear
• Pager: page is skipped (prev/next jumps over it)
• Home / chapter card grid: page doesn’t appear
• Search index: page is excluded
• The page still renders at its URL — only the listings change

Use this for draft pages, internal references, or any page you want reachable by URL but not advertised.

Rule 3 — Each section is its own pager scope #

The pager (prev/next) walks pages within the current section only. From the last page of chapter A, Next is empty (not the first page of chapter B). From the first page of chapter B, Previous goes back to the chapter B landing — not into chapter A.

This trades continuous flow for predictable bounded navigation. Readers use the sidebar (or / search) to jump between chapters.

If you want to opt a page out of the pager entirely, set nopager: true.

Rule 4 — Section pages are nav stops #

A _index.md is a navigable page. The pager treats it as the first item of its scope:

• Chapter landing → first lesson via Next
• First lesson → chapter landing via Previous
• Last lesson → no Next (end of chapter)

This means your chapter _index.md content matters — it’s the first thing readers hit when they enter the chapter, before any lesson.

Rule 5 — The home picks top-level sections #

/ (the home page) lists every top-level section in the site, sorted by weight, hidden filtered. Override the order or pick specific sections:

[params]
  homeSections = ["workshops", "guides", "reference"]

Without this param, the home shows all top-level sections in weight order.

Worked example #

Given:

content/
├── _index.md                                           # weight default
├── workshops/
│   ├── _index.md                                       # weight = 1
│   ├── getting-started/
│   │   ├── _index.md                                   # weight = 1
│   │   ├── 01-introduction.md                          # weight = 10
│   │   ├── 02-installation.md                          # weight = 20, hidden = true
│   │   └── 03-first-search.md                          # weight = 30
│   └── advanced/
│       ├── _index.md                                   # weight = 2
│       └── 01-pipelines.md                             # weight = 10
└── about.md                                            # weight default

Then:

That’s the entire model.