OINK 1.1.0 — Native locales, navigation, and site extensions

OINKThe project itself signs release notes and official announcements.

OINK 1.1.0 is the first minor release after the stable 1.0 contract. It completes the native interface catalogs, makes taxonomy roots useful as navigation directories, and addresses community feedback about sidebar state, keyboard focus, grouping, and search extensions. Existing 1.0 content and configuration need no source migration.

At a glance

• 32 native interface catalogs: all 31 locale names inherited from Docsy, plus generic zh, carry the same 194 OINK messages and locale-aware plurals.
• Taxonomy directories: tags, categories, authors, and series gain compact term cards, localized headings, and a switcher between declared taxonomies.
• Reliable navigation: cached trees preserve page settings, hidden sidebars leave the focus order, and divider sections keep their child documents.
• Site extension APIs: OinkSidebar exposes committed disclosure state; OinkCommandPalette.registerSearchTail adds query-aware site actions.
• Clean article copies: image zoom no longer inserts hidden preview instructions into text or HTML copied from an article.
• Correct Print and preview output: dedicated Print loses shell chrome, overlapping Book aggregates no longer race, and invalid component inputs retain their documented fallback behavior.

Native interface and taxonomy directories

All 32 locale catalogs now contain native OINK interface strings, without mechanically generated English fallback blocks. Page counts use Hugo’s CLDR plural selection, including languages that need more than singular and plural forms. Catalog checks cover missing or extra keys, duplicate entries, placeholders, plural forms, and hidden bidirectional controls. This translates the theme’s interface; each site still supplies its own translated content.

Taxonomy roots such as /tags/, /categories/, /authors/, and /series/ show a grid of compact term cards, ordered by usage. Taxonomy and term pages share a localized heading; their right rail links to the taxonomies declared by the site. Author cards can use portraits, while individual term pages keep their row-list archives. Breadcrumbs use the same localized taxonomy names.

Sidebar, grouping, and focus

Cached sidebar markup now respects the effective page and cascade settings that affect its output. It stays navigable without JavaScript, and active-path hydration avoids a temporary contrast drop. Book pages with page-specific sidebar headings bypass the shared tree cache.

The community fixes cover four related behaviors:

• #41: closing a sidebar or drawer isolates its hidden content from keyboard focus and assistive technology. The restore control, desktop hover reopening, mobile focus return, and Escape dismissal continue to work. Collapsing the entire right-hand outline also isolates it and transfers focus to its restore button. Groups moved into the mobile drawer remain usable even when that desktop rail was closed. The drawer’s Tab cycle includes only visible, active controls, so a collapsed branch cannot let focus escape into the page behind it.
• #42: sidebar_divider: true retains a section’s children under a non-link group label. Combine it with build.render: never to omit the group’s own page. Breadcrumbs have no dead group link; search and paging skip the group; Print and Book contents keep its children. Non-link group headings participate in tree keyboard navigation: Left / a returns to the group heading before collapsing it; Right / d expands the group before entering its children. The q / e shortcuts continue to move between page links only. Explicit navigation trees also resolve correctly with language and deployment path prefixes.
• #43: sidebar_root_menu: false applies to both top-level and self-root sections. The current linkable root still appears as the reader’s location marker; unpublished and divider sections do not become switcher links.
• #44: clicking a reading container no longer causes a large focus outline to appear after an unrelated key. Keyboard navigation and skip links retain visible focus indicators.

See content groups for the authoring recipe and the sidebar contract for runtime behavior.

Site-owned extensions

window.OinkSidebar provides a readiness promise, getState, setExpanded, and disclosure events. Readiness waits until the cached tree has restored its active path and the responsive shell has placed its groups, so a site’s saved state is not overwritten by later initialization. OINK commits the visual, ARIA, and inert states before notifying consumers. A site can use this API to persist reader-selected branches; storage and its version/language policy remain the site’s choice. Restoring saved state does not hide the active page’s ancestor path.

For #40, trusted site JavaScript can register search-tail rows through OinkCommandPalette.registerSearchTail({id, rows, activate}). The rows follow native results and actions after a non-empty text query has settled, including empty-result and error states. OINK owns row rendering, activation, cancellation, and an explicit handoff() for transferring focus to another site-owned surface. While an asynchronous action is pending, other palette rows cannot start competing actions, including native commands that open a choice list; activation is released when the pending action settles. See the integration example.

Both APIs are optional. Existing sites do not need scripts or configuration changes to adopt this release. Local search remains off by default, search extensions require that palette, and OINK includes no remote assistant, provider credentials, or query telemetry.

Copying, Print, and component fixes

With image zoom enabled, earlier versions inserted visually hidden preview instructions after each eligible image. Browser copying could include those words in both plain text and rich HTML, making them visible when a destination editor discarded the theme’s styles. Zoom buttons now carry the image description and localized action in their ARIA name instead. Authored images, alt text, captions, keyboard operation, and dialog focus return are preserved. The fix applies to ordinary image and gallery zoom triggers; zoom remains off by default. See image zoom.

Dedicated Docs and Blog Print output no longer includes the site navbar or interactive shell initialization. A single per-page coordinator renders plain and Book aggregate variants in a fixed order, avoiding shared Page Store races and preserving their intended heading and tab IDs.

Invalid book-toc drafts values keep the documented default after warning. A non-string Landing preview.source warns and omits only that section during an ordinary preview. Redoc local specification paths consistently resolve from static/, with or without a leading slash, under both root and subpath deployments; valid remote HTTP(S) URLs retain their behavior.

Compatibility

Hugo Extended 0.160.1 remains the compatibility floor; the pinned continuous integration toolchain is 0.165.0. The module still declares Go 1.27.0, as it did in 1.0.0. Node and npm are required for the documentation regression suite, not for an ordinary Hugo site build.

On Hugo 0.160.x, a non-default generic zh language alongside the regional Chinese catalogs needs locale: zh-CN. Bare locale: zh works in that configuration from Hugo 0.161 onward. Arabic, Persian, and Hebrew sites still set their language’s direction: rtl.

No component or configuration migration is required from 1.0.0. The taxonomy root layout changes visibly. Sites that override sidebar, taxonomy, Print, or image-zoom code should compare their overrides with the new theme: copied implementations do not inherit upstream fixes automatically. Site scripts using the new APIs should feature-detect them when supporting older releases.

The unused ScrollSpy patch no longer ships. params.ui.scroll_spy and the page-level scroll_spy key remain accepted as quiet no-ops throughout 1.x; OINK’s normal outline runtime already tracks the active heading. Compatibility partials, the supported search providers, and migration tools remain available.

Verification and publication

The implementation at 08f6563 passed the pinned-toolchain theme CI: Hugo checks, browser-runtime tests, and Book publication checks. The earlier community-fix acceptance and the subsequent bilingual image-copy regression are recorded in the upstream review. The additional initialization, action-concurrency, and keyboard-focus fixes and source acceptance are recorded in the release review. Local acceptance passed 44 JavaScript tests, 57 site tests, and 149 Chromium tests. Hugo Extended 0.160.1 also passed the selected compatibility checks and the real documentation site’s strict production build.

Output checkers now build fresh fixtures unless an explicit output directory is supplied. Checker-owned Hugo processes have a 120-second ceiling, and redundant warning-fatal builds were removed while retaining per-case diagnostic and fallback assertions.

The published v1.1.0 tag points to 3a18234, which adds only the finalized changelog to the accepted implementation and passed all three release-commit CI jobs. A fresh-cache download from the official Go module proxy resolved to that commit; the module archive and go.mod checksums were verified against sum.golang.org.

A theme release does not update consumer sites automatically. Each site still needs to pin the new module, build it without a filesystem replacement, and verify the deployed output.

Upgrade

Pin the published version and run a strict production build:

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy
hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings --panicOnWarning

Commit go.mod and go.sum. Check taxonomy directories, cached and mobile sidebars, grouped navigation, Print and Book output, and article copying, alongside the site’s language, light/dark, and subpath routes. Detailed steps are in the 1.0-to-1.1 upgrade checklist.

The repository-level change ledger remains in CHANGELOG.md.