Sequential reading and mathematics

Oink 0.4.0 gives manuals, Books, and blogs a defined reading sequence. The same release also makes server-rendered mathematics a first-class content path.

Enable or narrow the pager

The pager is enabled by default for the docs, book, and blog content types. Replace that set explicitly when a site uses only some of them:

params:
  ui:
    pager:
      types: [docs, book, blog]

Only those three type names are valid. A page or section can opt out with a boolean front matter value:

---
pager: false
---

Interactive HTML renders only the previous or next destination that exists and adds matching <link rel="prev"> and <link rel="next"> elements to the page head. Print, Markdown, and RSS contain no pager markup or relations.

Understand reading order

Docs and Books use a pre-order traversal of the same navigation root as the sidebar: a section index precedes its visible children, and ordinary children follow weight order. If data/docs_nav.json supplies an explicit tree, that tree is authoritative for both sidebar and pager.

These visible navigation entries are not destinations:

• pages hidden with toc_hide;
• link-only placeholders using manualLink or manualLinkRelref;
• non-linking rows marked sidebar_divider: true.

Blogs preserve Hugo’s section time order. This is deliberately different from the manual tree order.

Manuals normally live below the configured docs section. If manual pages deliberately live at the content root and /docs/ is only an overview, set:

params:
  ui:
    sidebar_root_enabled: true
    docs_root: home

docs_root accepts only section (the default) or home; an invalid value is a build error. With home, top-level toc_root: true overview sections remain outside the manual sequence.

Render delimiter mathematics

Hugo does not merge a theme’s Goldmark configuration into a consuming site, so the site must enable passthrough delimiters:

markup:
  goldmark:
    extensions:
      passthrough:
        enable: true
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]

Oink supplies the passthrough render hook and local KaTeX CSS. Formulae render server-side as KaTeX and MathML, and only formula pages receive the stylesheet. math: true by itself does not enable delimiter parsing.

Build a page containing both inline and display delimiters, then inspect the HTML for MathML rather than literal $$. Long display formulae scroll within the article column on screen and remain static in print.

Use the display-math escape hatch

When a site cannot enable Goldmark passthrough yet, use the parameter-free display form:

{{< eq >}}E = mc^2{{< /eq >}}

This form is intentionally unnumbered. It creates no anchor, caption, or Book registry entry and emits a plain $$ block in Markdown and RSS. To create a numbered, referenceable equation, adopt the Book equation form and add a quoted num.

Validate the reading experience

1. Compare sidebar order with the q/e shortcuts and visible pager.
2. Confirm link-only, divider, and hidden entries are skipped.
3. Inspect head relations at the first, middle, and last destination.
4. Build from a subpath and confirm pager links remain on the current origin.
5. Check that print, Markdown, and RSS omit interaction-only pager markup.
6. Test formula pages in both color modes and print, then confirm an ordinary page does not load KaTeX CSS.

See Keyboard navigation for all reading keys.