OINK 1.0.0 — Stable contracts, a supported starter, and a complete public release

OINKThe project itself signs release notes and official announcements.

OINK 1.0.0 is a stability milestone, not a last-minute API reset. It promotes the component, configuration, content, output, and maintainer contracts built through the 0.x releases to the first major version. This note rolls up every theme change in v0.8.0..v1.0.0; the 0.8.0 agent outputs and backlinks are the starting baseline rather than being counted again as new 1.0 work.

An existing 0.8.0, 0.8.1, or 0.8.2 site needs no content or configuration migration. Pin the new module, run the warning-strict build, and review the rendered site as you would for any theme upgrade.

At a glance

• The current authoring, shell, landing, Book, release, Print, Markdown, and agent-output contracts are now the OINK 1.0 stable surface.
• Single-page Print preserves ordinary page heading and footnote IDs; only multi-page section and whole-Book aggregates namespace page-local targets.
• Book sidebar numbers remain atomic beside long, wrapping titles.
• Theme CI, the documentation site, and OINK Starter use Go 1.27 and Hugo Extended 0.165.0. The declared Hugo compatibility floor remains Extended 0.160.1.
• OINK Starter is the supported first route into the framework, with neutral Docs, Blog, and Book content and strict GitHub Pages and Cloudflare Pages workflows.
• The README, theme metadata, case-study links, badges, and optimized 3:2 Hugo Themes gallery images now describe and present the same product that the code ships.

What 1.0 makes stable

The version number covers contracts, not a promise that the interface will stop evolving. OINK can keep adding components and optional outputs in 1.x; the point of 1.0 is that an ordinary site should not have to relearn or rewrite the current foundations on every minor release.

The normative English and Chinese records live under Design. Their status now reads released-v1.0.0; dated research and active proposals remain evidence or future work, not hidden 1.0 features.

Everything changed after 0.8.0

The complete source comparison is v0.8.0...v1.0.0. It contains a deliberately small stabilization set:

There is no component rename, configuration-key removal, default flip, or content-syntax migration in this range.

Correct Print identities

Page-local IDs and aggregate-document IDs solve different problems. An ordinary page and that page’s own Print representation are two views of the same document, so their authored or Goldmark-generated heading and footnote IDs should match. A section Print or whole-Book Print combines many source pages, so two chapters may both contain #overview or fn:1; those targets must gain a source-page namespace.

Book figures, tables, equations, examples, and rewritten cross-page links keep their existing explicit target rules. The fix narrows namespacing to the two outputs that actually aggregate documents.

A supported first mile

OINK Starter is now part of the supported release surface rather than an informal demo. It starts as a small, neutral project site: three language profiles, Docs, Blog, Book, local assets, and two warning-strict deployment workflows. It deliberately excludes OINK’s own analytics account, comments, brand, documentation corpus, browser suite, and maintainer fixtures.

The Starter tutorial moves from shallow changes to deep ones: establish an unchanged baseline, set identity, choose languages, replace home data, rewrite content and navigation, add brand, enable complete integrations, run the strict build, and only then deploy. Existing Hugo sites can still take the smaller module-from-scratch path.

Toolchain and compatibility

The official Hugo Themes update workflow moved to Go 1.27 and Hugo 0.165.0 on the day of this release. OINK 1.0 follows that current publication baseline:

The short-lived 0.8.2 patch lowered only the module’s go directive so the previous official updater, fixed on Go 1.26 with local toolchain selection, could admit the theme. Once upstream moved to 1.27, keeping that exception no longer described the release environment. OINK itself is still templates, styles, assets, and checkers rather than Go source. An offline archive or Git submodule installation does not ask Go to resolve the module.

Upgrade

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

Commit both go.mod and go.sum. Then inspect representative Docs, Blog, Book, Print, language, light/dark, and narrow-screen routes. A successful local build, the public tag, a resolved module checksum, a consumer pin, deployment, and live rendering remain separate release states.

The repository-level ledger remains in CHANGELOG.md.