What readers get automatically
Every rendered page ships with four reading-experience primitives that the platform wires in from your MDX source and nookdocs.config.json — you don't configure them per page.
Breadcrumb / section eyebrow
The parent group (or tab + group, in tabbed mode) renders as a muted link above the h1.
On this page
Every h2 and h3 in your MDX body appears in a sticky right-column TOC with scroll-spy highlighting.
Prev / next cards
Paired navigation cards at the end of each page use the flattened navigation order.
Last updated
A subtle timestamp under the footer shows when the page was last synced from your GitHub repo.
Breadcrumb
The breadcrumb reads from the navigation field in your nookdocs.config.json. The platform walks all groups to find which one contains the current page, then renders:
Single item (flat mode or tabbed mode with one-level nesting): a primary-colored "eyebrow" label above the h1, like
DocumentationMultiple items (nested groups or explicit tab + group): a classic chevron-separated trail, like
Documentation › Getting Started
No extra config. If the page is in the Getting Started group under the Documentation tab, the breadcrumb renders itself.
On narrow viewports the breadcrumb appears beside the menu button, and the group name is clickable — it opens the navigation drawer at that section. A group owns pages but has no page of its own, so the drawer is the destination.
Table of Contents
The right-column "On this page" list is generated by parsing your MDX source and extracting every h2 and h3 heading. Clicking a heading scrolls to it; the active heading highlights automatically as the reader scrolls using IntersectionObserver.
h1 is reserved for the page title (from frontmatter). The TOC never includes it. h4 and deeper headings are also skipped to keep the list scannable.
Heading IDs are auto-generated from the text:
## API Reference → #api-reference
## Create a project → #create-a-projectYou can override the slug with {#custom-id} syntax if you need stable anchors:
## Create a project {#new-project}Permalinks
Hovering an h2 or h3 reveals a link icon in the margin beside it. Clicking it copies that section's full URL to the clipboard and updates the address bar, so readers can share a specific section rather than the whole page.
Only headings you write as markdown ## / ### get an id and appear in the
TOC. Headings that components render — a <Card> title, an <ApiEndpoint>
section label — are part of that component's design, not landmarks in your
page, so they stay out of both.
A <Card> pointing at a section on the same page (href="#pricing") also shows
the permalink icon beside its title, since it names a section the same way a
heading does. Cards linking to another page don't — the whole card is already a
link there.
Prev / next navigation
Below the last paragraph of every page, readers see two cards linking to the previous and next pages in the flattened navigation sequence.
In tabbed mode, prev/next stay within the current tab. The Next button on the last Documentation page does not jump to the first Components page — each tab is a self-contained reading sequence.
Last updated
The timestamp is read from the pages.updated_at column, which is set every time the Trigger.dev sync job writes the page. In practice, this is the timestamp of the most recent git push that touched the file.
Writing for the reading experience
The primitives above just work, but a few authoring habits make them work better:
Lead with an h2. The first paragraph of your body is not an h1 — that is the
titlein frontmatter. The body should start with a section heading so the TOC has entries from the first scroll.Keep h2 and h3 scannable. Think of them as the table of contents entries, because they are.
Name your navigation groups like human sections. "Getting Started" works; "gs-v2-final" does not — the group name becomes the breadcrumb.
Order your nav entries thoughtfully. Prev/next walks the list in order, so bad ordering becomes bad reading flow.