Upgrade to Oink 0.4.0

Oink 0.4.0 is the consolidated Scenario Components release. Reading & Release, Landing, and Book were originally designed as 0.4, 0.5, and 0.6 tracks but ship together under the single public v0.4.0 tag. Do not pin the historical design numbers.

Ordinary Docsy-compatible content, existing homepage data, and the module path remain compatible. Most work is reviewing new default shell behavior and replacing two removed ICP-specific footer parameters.

1. Pin the immutable release

Create an upgrade branch and update the Hugo Module:

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy
hugo mod graph | grep github.com/pgsty/oink

The graph must resolve github.com/pgsty/[email protected], not a pseudo-version or main. Oink 0.4.0 requires Hugo Extended 0.160.1 or newer and still requires no consumer Node.js, PostCSS, or CDN pipeline.

When developing against a sibling checkout, remember that go.work overrides the public module pin. Validate the public tag separately with both GOWORK=off and HUGO_MODULE_WORKSPACE=off before calling the release dependency verified.

2. Review new defaults

Sequential pager

docs, book, and blog now receive a sequential pager by default. Docs and Books follow the visible sidebar tree; blogs follow time order. If a page or section deliberately has no sequence, opt it out:

---
pager: false
---

If site-root manuals already use params.ui.docs_root: home, confirm the pager and sidebar traverse the same intended tree. Do not create a separate pager manifest.

Universal navbar

The navbar now appears on every layout. Its compact state keeps one icon-based navigation row; there is no second mobile accordion. Remove local scripts or tests that assume a separate mobile menu. navbar_accordion_single_open is retired and ignored.

To preserve a deliberately navbar-free section, use the validated override:

cascade:
  navbar_enabled: false

The site setting lives at params.ui.navbar_enabled; a section cascade or page front matter sets the top-level navbar_enabled key. All three accept only a boolean, and the closest page value wins.

Site-wide footer

footer_style defaults to fat and now applies to every layout. It accepts only fat, slim, or none. Legacy footer data in data/home/<language>.yaml still works, but now appears site-wide instead of only on the homepage. Move it to data/footer/<language>.yaml when convenient.

Readers can collapse a fat footer’s link grid; the preference persists locally. Use slim for only the bottom line or none to remove the footer from a page or section.

Keyboard and page actions

Single-key navigation is enabled by default on docs, blog, and Swagger shells. The / key now opens full search, while \ opens command-only mode. Review any training text or custom scripts that assumed the previous / behavior.

Page actions now live in a split button beside the breadcrumb. Remove local CSS or browser tests that target the old collapsible TOC-rail action group. See Keyboard navigation for the complete key contract.

3. Replace removed footer parameters

Oink no longer reads the ICP-specific pair:

# Before 0.4.0
params:
  footer_icp: 京ICP备00000000号
  footer_icp_url: https://beian.miit.gov.cn/

Replace it with one inline-Markdown string:

# Oink 0.4.0
params:
  footer_center_info: '[京ICP备00000000号](https://beian.miit.gov.cn/)'

An explicit empty string hides the center region. When omitted, it defaults to Powered by Oink. Docsy’s params.copyright string/map contract and Hugo’s top-level copyright fallback remain supported.

4. Enable mathematics deliberately

If content uses \(...\), \[...\], or $$...$$, enable Goldmark passthrough in the consuming site because Hugo does not merge theme markup configuration:

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

The theme owns the render hook and local KaTeX assets. math: true alone is not an enable switch. Existing parameter-free eq calls remain valid and unnumbered; only a quoted num selects the Book form.

5. Adopt scenarios only where useful

No ordinary content conversion is required. Introduce the stricter models incrementally:

• Sequential reading is already active; configure only exceptions and root choice.
• Releases and downloads replace copied release URLs, checksums, and install commands with local facts.
• Landing pages replace bespoke full-width templates or new Docsy block-shortcode compositions. Existing homepage data remains compatible.
• Book publishing is opt-in. Inventory existing IDs, captions, references, and output requirements before conversion.

Legacy home/ partial names remain thin adapters, and Docsy block shortcodes still render. They are compatibility paths, not the recommended basis for new Landing work.

6. Run the upgrade matrix

Build every language and output from both the production base URL and a subpath preview. At minimum inspect:

For this official project site, the complete consumer gate is:

npm test
npm run test:browser

For another site, run its equivalent build, link, output, accessibility, and browser checks. A green local build does not prove the signed tag, public module cache, hosted deployment, or CDN state; record each separately.

Roll back safely

If the site-specific migration fails, restore the prior pinned release in go.mod and rebuild. Do not delete authored content or reset the worktree as a rollback shortcut. Keep the upgrade branch and validation evidence so the failing contract can be corrected without losing unrelated work.

See the 0.4.0 release note for the complete feature and behavior summary.