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

> OINK 1.0.0 makes the current knowledge-publishing contracts stable and rolls up every theme change since 0.8.0: Print and Book correctness, pinned Go 1.27 and Hugo 0.165.0 release tooling, a supported Starter, and the public metadata and media needed to enter the wider Hugo ecosystem.

---

LLMS index: [llms.txt](/llms.txt)

---

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.

**v1\.0\.0 · 2026-08-29**
- [View release](https://github.com/pgsty/oink/releases/tag/v1.0.0)
- [Source · tar\.gz](https://github.com/pgsty/oink/archive/refs/tags/v1.0.0.tar.gz)
- [Source · zip](https://github.com/pgsty/oink/archive/refs/tags/v1.0.0.zip)
- [pgsty\/oink](https://github.com/pgsty/oink)

## At a glance {#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 {#stable-contracts}

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.

| Surface | 1.0 contract |
| --- | --- |
| Content | Native Markdown remains the source; components preserve explicit static degradation for non-interactive outputs |
| Configuration | `params.ui.*` owns theme policy, page overrides drop the prefix, and invalid author input warns with a safe fallback |
| Shells | Docs, Blog, Book, Swagger/Redoc, and Landing keep distinct, documented responsibilities |
| Outputs | HTML, RSS, Print, Markdown, LLMS, LLMSFULL, NAVJSON, and BookManifest keep explicit opt-in and degradation boundaries |
| Runtime | Vendored assets stay local and capability code loads only where rendered content needs it |
| Maintenance | Implementation, owning checker, bilingual contract, release state, consumer pin, and deployment remain separate evidence |

The normative English and Chinese records live under
[Design](/docs/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 {#changes-since-080}

The complete source comparison is
[`v0.8.0...v1.0.0`](https://github.com/pgsty/oink/compare/v0.8.0...v1.0.0).
It contains a deliberately small stabilization set:

| Area | Change | User-visible effect |
| --- | --- | --- |
| Book sidebar | Fixed the number cell and added a compiled-CSS regression assertion | A long title wraps without compressing, clipping, or splitting its chapter number |
| Print anchors | Distinguished a page Print from section and Book aggregates, then refreshed the output golden | A fragment valid on an ordinary page remains valid on that page's Print view; aggregate IDs remain collision-free |
| Theme CI | Replaced the historical Hugo matrix with one pinned Extended 0.165.0 toolchain and explicitly pinned Go 1.27 for module-mode coverage | Release evidence now matches the current upstream toolchain while the 0.160.1 Hugo floor stays documented separately |
| Public README | Rebuilt the first-run path around OINK Starter, capability and compatibility tables, production cases, docs links, and the Docsy boundary | A visitor can evaluate the project without reverse-engineering its regression site |
| Hugo Themes media | Replaced the old captures with optimized 3:2 landing-page images | The gallery receives the required aspect ratio at 166,526-byte and 68,488-byte PNG sizes without browser chrome |
| Theme metadata | Expanded the description, tags, and features; normalized the OINK wordmark; recorded Docsy as the original theme | Catalogue attribution and discovery now match the repository's actual scope |
| Module directive | 0.8.2 temporarily admitted the module to the former Go 1.26 upstream builder; 1.0 follows the newly updated upstream workflow on Go 1.27 | This changes module admission only; OINK still contains no Go source and the rendered theme is unchanged by the directive |

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

## Correct Print identities {#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.

| Output | Heading and footnote IDs |
| --- | --- |
| Ordinary HTML page | Authored or Goldmark-generated page-local IDs |
| Single-page Print | The same page-local IDs as ordinary HTML |
| Multi-page section Print | Source-page namespace added |
| Whole-Book Print | Source-page namespace added |

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 {#supported-starter}

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](/docs/start/starter/) 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](/docs/start/from-scratch/).

## Toolchain and compatibility {#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:

| Dependency | OINK 1.0 policy |
| --- | --- |
| Hugo | Extended 0.160.1 or newer; release, site, and browser validation pin 0.165.0 |
| Go | 1.27 or newer for Hugo Module resolution |
| Node.js | Not required to build or run a consumer site |

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 {#upgrade}

```bash
hugo mod get github.com/pgsty/oink@v1.0.0
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](https://github.com/pgsty/oink/blob/main/CHANGELOG.md).