Oink Release Notes

• 1: Oink 0.4.0 — Scenario components for complete publishing workflows
• 2: Oink 0.3.0 — Authoring, navigation, and a lighter page
• 3: Oink 0.2.0 — Richer content and sharper presentation
• 4: Oink 0.1.0 — A stable local-first foundation

1 - Oink 0.4.0 — Scenario components for complete publishing workflows

Release date: 2026-08-14 · Signed theme tag: v0.4.0 · Repository: pgsty/oink

Oink 0.4.0 delivers the complete Scenario Components system. The original design separated Reading & Release, Landing, and Book work into 0.4, 0.5, and 0.6 milestones. The public release consolidates those tracks into one signed v0.4.0 tag so consumers can adopt one coherent contract instead of a chain of interdependent previews.

The release remains local-first: consumer sites still build with Hugo Extended and Go, without Node.js, a browser-time API, or a CDN. Interactive behavior is progressive enhancement; HTML, print, Markdown, and RSS output retain the content needed to understand each surface.

Release highlights

Reading and release

Documentation, Book, and blog pages now have a sequential pager derived from the same flattened navigation tree readers see in the sidebar. Previous and next links also appear as same-origin rel metadata in the document head. Explicit navigation data, link-only entries, sidebar dividers, and blog time order keep their own semantics instead of becoming accidental destinations.

Math can use Goldmark passthrough with the theme’s local KaTeX renderer. Sites that cannot enable passthrough yet have a strict, parameter-free eq escape hatch for display math. Numbered Book equations use the same shortcode only when an explicit num is supplied.

Release pages can render local front-matter facts, release cards, checksums, and asset lists without querying GitHub from the browser. A validated data/download/<key>.yaml model feeds both the download shortcode and Landing download sections, with separate rolling and pinned channels and an explicit pending-release state.

See Sequential reading and mathematics and Releases and downloads for the complete contracts.

Landing pages

The data-driven homepage renderer is now a reusable layout: landing shell for ordinary pages. A page may load inline data or language-aware records from data/landing/<key>/, then compose 21 built-in sections including pricing, comparison tables, command boxes, steps, timelines, code plates, case studies, downloads, and bar charts.

All facts are local at build time. Optional reveal, count-up, copy, theme-image, and compact-menu behavior loads only when a Landing page needs it. Without JavaScript, the same page remains complete; marquees pause on focus or request, respect reduced motion, and hide duplicate tracks from assistive technology.

See Landing pages for data resolution, all 21 section types, local-fact rules, and the output matrix.

Book publishing

Long-form manuals can declare Book metadata on the existing documentation shell. Chapters gain draft labels, active-page sidebar headings, and semantic fig, tbl, numbered eq, and language-aware xref targets. Whole-Book figure lists and tables of contents use those same registries.

An opt-in aggregate print document rewrites cross-chapter component links into document-local references and namespaces repeated heading IDs. The accompanying migration tool is dry-run first and idempotent, with reproducible TPME, DDIA, and pg-internal recipes, machine-readable reports, ambiguity skips, and a second-run zero-change check.

See Book publishing for the authoring and migration contract.

Keyboard and shell

The shell now supports single-key reading navigation. w and s move through the sidebar, a and d fold or unfold groups, j and k move through the page outline, and q and e follow the sequential pager. h toggles a session reading mode; l, t, f, and c switch language, theme, search, and command surfaces. Every binding yields to editable controls, composition, held modifiers, and dialogs.

The navbar now spans documentation, blog, taxonomy, and Swagger layouts with one compact state instead of a second mobile menu. Page actions move into the breadcrumb row as a Copy Markdown split button. Footers support validated fat, slim, and none styles, while readers can collapse the fat footer’s link grid and retain that preference.

See Keyboard navigation and Navigation and menus.

Compatibility and behavior changes

• Hugo Extended 0.160.1 remains the minimum supported version.
• The module path remains github.com/pgsty/oink; consumers still need no frontend toolchain.
• Pagers default to the docs, book, and blog content types. Set an explicit type list or pager: false when a page should opt out.
• / now opens full search; \ opens command-only mode. The > prefix still selects command mode inside the Palette.
• params.footer_icp and params.footer_icp_url are replaced by one inline Markdown value, params.footer_center_info. An explicit empty string hides the center region.
• params.ui.navbar_enabled defaults to true. Sites can override it globally, by section cascade, or on one page.
• Legacy homepage data and Docsy block shortcodes remain compatible, but new Landing work should use the canonical section registry.

Upgrade to 0.4.0

1. Pin the signed tag and tidy the module graph.
2. Replace ICP-specific footer fields with footer_center_info if the site used them.
3. Review pager defaults, / and \ shortcuts, and any local navbar or footer overrides.
4. Remove copied theme partials only after comparing their local differences with the 0.4 implementation.
5. Build representative docs, blog, Landing, Book, print, Markdown, mobile, and color-mode surfaces.

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy
hugo --gc --minify

Follow the project-site 0.4.0 upgrade guide for the consumer checklist. The theme repository retains the frozen PRD 5 migration reference.

Verification

The signed tag resolves to the same commit as the released theme source. Theme CI exercises Hugo Extended 0.160.1 and 0.164.0, 32-locale parity, vendored assets, runtime unit tests, every PRD 4/5/6 contract, and the warning-strict example site. The project site pins the public tag and covers bilingual source, rendered Markdown, internal links, alternate builds, browser behavior, and the full multilingual WCAG AA matrix.

Representative documentation, portal, Book, and archive sites also build from the public v0.4.0 module with workspaces disabled.

Source validation, a public tag, a consumer pin, and hosted deployment are separate evidence gates. Publishing this note does not replace a smoke test of the deployed URL after the site pipeline finishes.

Full change set

See the complete source diff from v0.3.0 to v0.4.0.

2 - Oink 0.3.0 — Authoring, navigation, and a lighter page

Release date: 2026-08-12 · Theme tag: v0.3.0 · Repository: pgsty/oink

Publication gate: the linked tag must resolve, the project site must pin that exact tag, and the hosted checks must pass. Until then, treat this source page as release-candidate material.

Oink 0.3.0 is the authoring and navigation release. Writing a page gets a modern code-block presentation and a set of small, everyday components; reading one gets nested navigation and a Command Palette; and every page gets measurably lighter because jQuery is gone.

The module path, the minimum Hugo version, and the Hugo-only consumer build are unchanged. Three changes can affect an existing site and are documented in Breaking changes.

Release highlights

Code blocks and code groups

Ordinary fenced code blocks now render a real code surface: an optional filename, a language label, a copy button rendered by the server rather than injected by script, opt-in wrapping, and collapsing for long listings. Hugo’s own highlighting options — line numbers, line anchors, hl_lines, tab width — keep working exactly as before.

Copy behaviour is deterministic rather than guessed. Session lexers such as console and shell-session default to copying commands without prompts and output; every other language copies the whole block. copy=command is rejected on lexers that cannot distinguish the two, because silently copying the wrong thing is worse than a build error.

The code-group shortcode groups alternatives — package managers, languages, platforms — into synchronized tabs with a stable URL hash, so a link can open the exact variant a reader needs. Legacy tabpane content keeps working and keeps its storage key.

See Code blocks for the full attribute contract.

Everyday content primitives

Alongside the existing large components, 0.3.0 adds the small ones authors actually reach for daily: badge, kbd, fields, filetree, gallery, and an opt-in image_zoom. All of them render semantic HTML, none of the non-interactive ones load JavaScript, and each has a defined presentation in print and Markdown output as well as HTML.

A standalone public icon shortcode is deliberately still deferred; components use a private, allowlisted registry for their own decoration until that API is designed properly.

See Components for each contract.

Navigation and Command Palette

Top-level menus support one level of dropdowns on desktop and matching accordions on mobile, with the parent link and the disclosure control operated independently so a parent stays navigable. Flat menus are untouched.

Local search becomes a Command Palette with three modes: an empty query offering quick links and page actions, a text query returning grouped page results, and a > prefix that searches commands only. Pages can contribute search_keywords, a positive search_boost, and canonical exclusion; ranking applies the same boost on both the Lunr and CJK substring paths.

Page actions and palette commands now run through one shared registry, so Copy text, Open in ChatGPT, Open in Claude, View source, View edit history, printing, and switching theme, language, or version behave identically wherever they are invoked. Assistant prompts resolve the browser URL at activation time, preserving the deployed host, query string, and fragment; history links derive from the same repository path as Edit this page. Assistant handoff links are disabled by default; sites must opt in with params.ui.page_context_menu.assistant_links: true. On activation, the full URL leaves the site, so do not place secrets in its query or fragment.

Press / outside an editable control to open the Palette directly in command mode. Cmd/Ctrl-K remains the general entry point, and the single-character shortcut yields to inputs, textareas, selects, and contenteditable regions.

Sidebars gain an icon-density policy — all, groups, or none. The compatibility default stays all; the starter example opts into groups.

See the migration reference for the complete configuration surface.

Typography presets

Font choices move behind seven semantic --td-*-font-family roles covering UI, body, headings, code, display text, metadata, and print. Two validated presets ship: technical, which preserves the current Oink appearance, and system, which uses the platform stack and requests no Oink brand fonts at all. Existing Docsy and Bootstrap Sass font variables seed the roles, so prior overrides keep working.

This is the typography slice of a larger design-token effort. Colour, surface, radius, density, and appearance presets are not part of this release.

See Typography tokens.

A lighter page

jQuery is gone. It was previously fetched render-blocking in <head> on every page — 87.5 KB before any content — while the theme’s own architecture loads feature runtimes only on pages that use them. Nothing in the shell needed it, and the superseded offline-search.js runtime it powered was already replaced by the Command Palette.

Two other costs were removed rather than accepted. The active output format is now read from the page store instead of being re-derived thousands of times per build, and the shell configuration is cached per language; on a 576-page build that is 357ms of template time reduced to 72ms, with byte-identical output. CJK search folds its index fields once instead of re-lowercasing the entire corpus on every keystroke, taking an 800-document query from 3.44ms to 0.34ms per character typed.

On the measured project-site snapshot, removing jQuery and the superseded search runtime saved about 88 KB from a typical documentation page’s combined CSS and JavaScript. Exact totals vary as later candidate assets change.

Correctness and localization

This release also closes several less visible correctness gaps. Markdown pages link to llms.txt only when the active language actually publishes one, and the index no longer treats off-site menu chrome as content. Internal configured commands stay under a subpath deployment, while shared content types resolve to the right product root. The archived-version banner and Giscus fallback are now localized, and print or Markdown output strips interaction-only Image Zoom attributes regardless of quoting style. Legacy search links also percent-encode their query text instead of truncating a query at &.

Browser runtime tests now run in theme CI instead of relying on Hugo bundling as their only signal. Terminal recordings also wait for their configured font before fitting the player, avoiding geometry based on a fallback font.

Breaking changes

jQuery is no longer loaded. The third-party inventory previously listed it as part of the UI foundation, so a consuming site’s own scripts may rely on the global $. No theme feature requires it. Sites that need it must now bundle it through project JavaScript:

<!-- layouts/_partials/hooks/head-end.html -->
<script src="{{ (resources.Get "js/jquery.min.js").RelPermalink }}"></script>

static/js/tabpane-persist.js is removed. assets/js/code-tabs.js took over the legacy persistence contract, keeping the td-tp-persist storage key and data attribute, so authored tab content is unaffected. Only a site that referenced the published file path directly needs to drop that reference.

Body and heading typography roles apply directly to content. A site that previously restyled raw body or heading selectors should move to the matching --td-*-font-family role or the established Sass variable:

// Before
body {
  font-family: 'My Sans', sans-serif;
}

// Oink 0.3.0
:root {
  --td-body-font-family: 'My Sans', sans-serif;
}

Upgrade to 0.3.0

1. Check whether any project JavaScript depends on the global $, and bundle jQuery yourself if so.
2. Remove any direct reference to static/js/tabpane-persist.js; authored tabpane content itself does not change.
3. Move raw body or heading font overrides to the typography roles.
4. Decide whether to opt into assistant handoff links. If enabled, review URLs for sensitive query or fragment data and disclose the third-party boundary.
5. Update the Hugo Module and tidy the module graph.
6. Build and inspect representative documentation, blog, mobile, print, and color-mode pages.

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy
hugo --gc --minify

No Markdown content rewrite is required. Existing fenced code blocks, tabpane content, flat menus, shortcodes, and ordinary Docsy-compatible pages continue to work unchanged.

Compatibility

Verification

The 0.3.0 candidate is exercised through the sibling Oink project site, so the site builds against the candidate theme rather than its last pinned release. Before publication, the theme gate must pass the complete contract suite, a warning-free example-site build on the minimum and current Hugo versions, both typography presets, and the browser runtime unit tests. The site gate must pass formatting, bilingual page pairs and stable heading IDs, rendered Markdown and internal links, Hugo Module fixtures, alternate-configuration builds, Markdown and favicon goldens, responsive and component browser behaviour, and axe accessibility checks. The tag, public-module resolution, site version pin, and hosted smoke tests remain separate post-approval gates.

Full change set

See the complete source diff from v0.2.1 to v0.3.0.

3 - Oink 0.2.0 — Richer content and sharper presentation

Release date: 2026-08-10 · Theme tag: v0.2.0 · Repository: pgsty/oink

Oink 0.2.0 focuses on the parts readers and authors touch most: the homepage, brand presentation, blog discovery, section indexes, and instructional content. It also turns the Oink project site into a clearer bilingual reference for the theme’s current contracts.

The module path, minimum Hugo version, and Hugo-only consumer build remain unchanged. The one configuration rename that can affect an existing site is documented in Breaking change.

Release highlights

Homepage and brand

The homepage now composes 12 built-in section types from an ordered sections list. A string selects data with the same name; a map can reuse a presentation through a different key, disable a block without deleting its data, or carry a small one-off block inline. Sites without sections retain the 0.1.x homepage order, so explicit composition is additive rather than a required migration.

The data-driven homepage can now place responsive artwork beside the Hero. Authors may configure one shared image or separate Light and Dark sources, plus meaningful alternative text when the artwork carries information. The layout adapts from a two-column desktop Hero to a compact mobile presentation without requiring a site-level template override.

Oink also adds params.wordmark. A configured wordmark is used consistently in the landing navigation, documentation header, drawer, and footer; sites that only configure params.logo keep the existing mark-plus-title presentation.

Component boards on the homepage can become real navigation. Items accept links, optional external-link behavior, compact styling, and one to four columns. Decorative boards remain non-interactive, preserving the 0.1.0 contract.

See Homepage and footer for the complete data shape.

Blog and release publishing

Blog rows now treat images and summaries as one responsive layout. Featured images no longer force the text outside tablet-width containers, summaries can break long machine-generated tokens, and posts without images use the full text width. The byline’s section name is now a link, and RSS moves into the same action rail used by the rest of the page.

Categories and tags use the same collapsible group grammar as the TOC and page actions. Terms render as scan-friendly rows with count badges in both the wide rail and the mobile drawer. Section indexes are quieter, descriptions have more room, and last-modified metadata follows the child-page index instead of interrupting the page introduction.

The Oink project site now separates upstream Docsy history, Oink engineering articles, and versioned Oink release notes into distinct bilingual sections. That makes release reports discoverable without presenting inherited Docsy posts as Oink releases.

Content components

0.2.0 adds a Markdown-first steps shortcode. Direct child headings become automatically numbered steps connected by a guide line; moving, adding, or removing a step updates the visible sequence without maintaining numbers by hand. Authors can mark a supporting heading with class="no-step-marker" so it does not consume a number.

Asciinema recordings gain a polished terminal frame, title bar, compact control bar, color-mode-aware styling, and a font contract passed directly into the player. This avoids the player falling back to a different terminal font while keeping recordings responsive and readable in both themes.

ECharts callback blocks keep the established trusted-author model: callback code is executable content that must be reviewed like inline HTML or another custom integration. The renderer no longer emits a redundant warning for every reviewed callback block.

See Shortcodes for the new steps contract and Oink components for the broader component model.

Documentation and tests

The independent project site receives a matching documentation pass:

• Expands English and Chinese homepage and component examples.
• Documents all 12 composable homepage sections and uses the relevant ones on the project landing page.
• Adds a real Asciinema installation recording and a dedicated giscus guide.
• Moves examples under the documentation tree and removes obsolete community and maintainer-only pages.
• Consolidates Hugo configuration into the root hugo.yml and retires the old Netlify-specific tooling.
• Isolates browser tests from live reload and keeps responsive, accessibility, translation, rendered-Markdown, and link checks in the release gate.

These are project-site changes, not new runtime dependencies for theme consumers.

Breaking change

0.2.0 renames the inherited featured-image setting from default_featured_image to default_featured. Update page, section cascade, and site-level configuration where the old key appears:

# Oink 0.1.x
default_featured_image: /images/blog-card.webp

# Oink 0.2.0
default_featured: /images/blog-card.webp

The implicit theme placeholder is also removed. If no post image, matching page resource, or explicit default_featured exists, Oink now renders a clean text-only list entry. Set default_featured to a site-owned image when a whole section should keep a visual identity; set it to false to make the opt-out explicit.

There is no compatibility alias for the old key. This is the only required configuration migration in 0.2.0.

Upgrade to 0.2.0

1. Replace every default_featured_image setting with default_featured.
2. Update the Hugo Module and tidy the module graph.
3. Build the site and inspect representative homepage, blog, documentation, mobile, and color-mode pages.

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy
hugo --gc --minify

No Markdown content rewrite is required. Existing homepage sections, logo-only branding, shortcodes, and ordinary Docsy-compatible pages continue to work.

Compatibility

Verification

The 0.2.0 candidate is exercised through the sibling Oink project site so the site builds against the candidate theme rather than only its last pinned release. The release gate covers formatting, bilingual page pairs and stable heading IDs, rendered Markdown and internal links, Hugo Module fixtures, responsive browser behavior, and axe accessibility checks.

Full change set

See the complete source diff from v0.1.0 to v0.2.0.

4 - Oink 0.1.0 — A stable local-first foundation

Release date: 2026-08-10 · Theme tag: v0.1.0 · Repository: pgsty/oink

Oink 0.1.0 is the first stable release of the Oink theme. It incorporates the 0.0.1 implementation preview and the stabilization work that followed: one coherent documentation shell, a Hugo-only consumer build, local-first browser assets, multilingual behavior derived from Hugo, and reusable content components.

This release keeps the module path github.com/pgsty/oink and requires Hugo Extended 0.160.1 or newer. A consuming site does not need Node.js, npm, PostCSS, Autoprefixer, or a CDN to build and serve theme-owned functionality.

Release highlights

Local-first theme foundation

Oink ships the styles, fonts, icons, local search, diagrams, API documentation runtimes, and content-component runtimes that it owns. Optional assets load only on pages that use them, and the distributable repository is a root Hugo Module rather than an embedded project site or frontend workspace.

The release also establishes the core product contracts:

• Hugo languages and translation objects drive language routes, switching, hreflang, writing direction, and locale metadata.
• The theme supports single-language, multilingual, and RTL sites without PGSTY-specific domain assumptions.
• Asciinema, ECharts, Infographic, diagrams, API references, tabs, cards, and other reusable components share local, page-scoped runtimes.
• GitHub Discussions comments are available through an opt-in giscus integration. No external comments script loads unless a site enables it.
• Docsy-compatible content organization, menus, taxonomies, print outputs, and extension hooks remain available.

Responsive shell

The documentation, blog, and API-reference layouts now use one responsive shell. Desktop navigation, the resizable sidebar, the table of contents (TOC), page actions, taxonomies, version selection, and the footer follow the same visual and interaction grammar.

On tablets and phones, Oink moves the TOC, page actions, categories, and tags into the navigation drawer instead of rendering a second copy. This preserves unique IDs and keeps scroll tracking, disclosures, and copy actions working across live viewport changes. Language and color controls remain reachable at every width, and the color selector exposes Auto, Light, and Dark as explicit preferences.

Navigation entries gain consistent icons, the mobile menu traps keyboard focus, footer columns fill the available width, and the compact page-action menu no longer duplicates the right rail. Copy Markdown, view Markdown, edit, issue, and print actions now come from one implementation.

Publishing and content

Syntax highlighting now uses class-based Chroma output with coordinated light and dark palettes. Code remains readable before JavaScript initializes a color mode, and sites can still opt out with params.highlight_classes: false.

Blog lists gain a deterministic featured-image resolver. In 0.1.0, it checks front matter images, a matching page resource, inherited default_featured_image, site parameters, and finally the theme placeholder. The same resolver serves both modern blog rows and the compatible legacy partial.

The new ink-mark logo and the placeholder artwork respond correctly to all four system-theme and selected-theme combinations. Oink now declares the used color-scheme in both directions, so an explicit site preference wins over the operating-system preference.

Accessibility and correctness

0.1.0 fixes a set of issues found during desktop, mobile, print, and assistive technology review:

• Corrects heading order, landmark names, task-list labels, and printable list semantics.
• Keeps blog rows inside the viewport at tablet widths and lets long URLs or identifiers wrap safely.
• Builds GitHub issue links with correctly encoded titles and URLs.
• Localizes the 404 page and removes hard-coded punctuation from translated accessible names.
• Gives iframe embeds titles and lazy loading, registers their resize helper once, and safely handles cross-origin frames.
• Emits one contentinfo landmark per page and keeps theme extension partials and opt-in SCSS entry points available to consumer sites.

The compatibility audit also removes genuinely unreachable legacy shell code while restoring files that downstream sites can import directly. Reachability is evaluated from consumer layouts and _styles_project.scss, not only from the theme’s own entry points.

Upgrade to 0.1.0

Update the Hugo Module and rebuild the site:

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy
hugo --gc --minify

No content migration is required. If a site imports Oink partials or SCSS directly, build that site as part of the upgrade so its customization surface is checked alongside the theme.

Compatibility

Verification

The final 0.1.0 candidate was swept against the theme fixture and the Oink project site across seven viewport widths. The recorded run reported no console errors, failed requests, horizontal overflow, or axe violations. Separate fixtures cover minimum and current Hugo versions, LTR and RTL languages, subpaths, print output, repeated component instances, and network-isolated consumer builds.

Full change set

See the v0.1.0 source snapshot.