The reading experience
None of this needs configuring. It is what every trail site does, and it is here so you know what your readers have — and so you can write pages that make use of it.
Search #
⌘K — or Ctrl K, and the pills in the header say which, based on the reader's platform — opens a search modal from any page. So does clicking the search box in the header or the one on the front page.
Search is powered by a Pagefind index built at build time. The engine and its index chunks load lazily, on the first open, so a reader who never searches pays nothing for it.
- Results show the page title, its breadcrumb trail, and an excerpt with the matches highlighted.
- Up to eight results are shown; the status line says how many more there were.
- ↑ and ↓ move; Enter opens; Esc or a click on the backdrop closes.
- The query is carried through to the page, which highlights every occurrence of each term in the article body and scrolls the first into view. Matches inside code blocks and breadcrumbs are skipped.
What is indexed is the article body. Chrome — breadcrumbs, the meta line, Related Content, the pager, the edit link — is excluded, and so is the front page and every alias page.
Commands #
A query beginning with / is a command rather than a search. Typing / on its own lists the ones this page has; typing more narrows the list, and Enter runs the highlighted one.
| Command | |
|---|---|
/theme | Cycles system → light → dark, exactly as the header button does. |
/theme <name> | Goes straight to system, light or dark. |
/cachebust, /cb | Opens the page you are on in the cache-busting copy — a URL nothing has cached. From inside the copy it takes you back out to the real page. Offered only when the build published a copy. |
Nothing needs enabling. The commands a page offers are the ones that can do something there, which is why /cb appears on a site built with --cbpath and nowhere else.
Light, dark and system #
The header's theme button cycles system → light → dark, and its icon shows which state is active. The choice is remembered in the reader's browser and applied before first paint, so there is no flash of the wrong theme.
"System" is the default and follows the operating system's preference live. See Theming.
Navigation #
The sidebar on an article page shows the article's own topic — its title above its contents in reading order, subfolders as collapsible groups (expanded automatically around the current page), and the current article marked. In a book it is the whole book as a tree with section numbers, chapters collapsible, and the trail to the current page opened. Chapters a reader opens by hand stay open as they move through the book, for that tab.
"On this page" lists the article's h2 and h3 headings in a right-hand column, and highlights the one currently in view as the reader scrolls. When the window is too narrow for a third column it moves into the sidebar. An article with no headings gets no list.
Every heading has a permalink — a # that appears on hover and links to that heading's stable id.
Previous and next links at the foot of an article step through the whole topic, or the whole book, in reading order.
Breadcrumbs run from the product down through anthologies, the topic and any subfolder.
A back-to-top button appears once the page has been scrolled past about 600 pixels.
Text size #
Three buttons at the top of the right-hand column set the prose to small, medium or large. The choice is remembered per reader.
It scales the article text only — the sidebar, header and chrome stay put. Making the whole page bigger costs a reader half their screen; making the prose bigger is what they actually wanted. On narrow screens the controls ride into the drawer with the rest of the sidebar.
Code and content #
- Every code block has a copy button, top-right, appearing on hover and always visible on touch devices. It says "Copied" briefly, and falls back to telling the reader to press ⌘C if the browser refuses clipboard access.
- Syntax highlighting follows the theme, because it is class-based rather than baked-in colours.
- Tables scroll inside their own container, so a wide table never makes the whole page scroll sideways.
- Images carry their real dimensions, so text does not jump around as they load.
- Tab groups keep one panel open at a time, independently per group.
- Mermaid diagrams are drawn in the reader's theme, and the library is only shipped to pages that contain one.
Page furniture #
A meta line under the title gives the estimated reading time and, when the article has an updated: date, when it last changed. Containers total theirs up, so a book cover says how long the whole book takes.
A "Single page" link in the breadcrumbs opens the whole topic or book as one page, anchored at the article the reader was on. It is the right link for someone who wants to read the lot, print it, or search the whole document at once. See The output surface.
"Edit this page" appears at the foot of every article when the site config sets edit_url, pointing at the article's source file.
A "Related Content" list appears above the pager when the article's frontmatter has a related: list.
On small screens #
The sidebar becomes a drawer, opened by the menu button in the header and closed by the overlay, the button again, or following any link inside it. "On this page" and the text-size controls ride in with it, so nothing is lost on a phone.
On paper #
Every page prints. The header, footer, search modal, pager, "Single page" link and back-to-top button all drop out; tab groups expand so every panel is visible, each labelled with its tab's name.
For printing a whole topic or book, use its /print view rather than printing pages one at a time.
Without JavaScript #
The pages are static HTML and read fine with scripts disabled. What is lost is the interactive layer: search, the theme toggle, text size, copy buttons, tab switching, the drawer, scroll-spying and diagram rendering. Content, navigation links, the sidebar tree and every ~link work regardless.