Design on OINK

Architecture contract

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 contract

This is the architecture contract released with OINK 0.8.0. This page is the canonical English source; its Chinese peer is maintained beside it in content/docs/design/.

Repository and assembly

The repository root is a Hugo Module and complete theme, not a site or npm workspace. Hugo Extended compiles SCSS and templates. Browser runtimes and third-party assets are committed, so a normal build performs no network fetch. Public bilingual documentation, examples, and browser tests live in the sibling oink.pgsty.com repository; the theme repository keeps only narrow internal regression fixtures under tests/site/ and has no separate public example surface.

Warnings and safe fallbacks

Mon, 01 Jan 0001 00:00:00 +0000

Decision

OINK does not call Hugo’s errorf. Invalid author or site input emits a warning and either uses a documented safe fallback or omits the invalid fragment. Release and deployment builds use --panicOnWarning, so the same warning remains a hard publishing failure.

Context

Hugo builds the whole site as one transaction. An errorf raised while one page is being edited makes every URL served by that rebuild return an error, including unrelated pages and the home page. The server process survives and recovers after the input is fixed, but collaborative preview is unavailable in the meantime.

Goldmark block-attribute evidence

Mon, 01 Jan 0001 00:00:00 +0000

Verified snapshot

These probes produced byte-identical relevant output on Hugo Extended 0.160.1 and 0.164.0. They explain OINK’s native component forms; the current component contract remains authoritative.

Method

The probe used a minimal Hugo site without OINK templates. Render hooks printed their context fields and .Attributes as visible markers. The site enabled Goldmark block attributes, passthrough delimiters for inline and block math, unsafe rendering for the deliberately inspected raw HTML, and wrapStandAloneImageWithinParagraph: false.

Backlinks and knowledge graph

Mon, 01 Jan 0001 00:00:00 +0000

G1 implemented; G2/G3 remain draft

On 2026-08-27 every G1 open decision was resolved and G1 (static backlinks) was accepted. It is implemented on the theme’s main branch and ships with OINK 0.8.0. The local and global graphs (G2/G3) stay draft pending real-world evidence from G1; their names and configuration are not public API until accepted.

Premise

Reverse navigation and a view of connected pages are properties of the link graph, not of [[wikilink]] spelling. Hugo already accepts ordinary Markdown links and ref / relref. OINK can derive a graph from content authors already write, without adding a parser, Goldmark extension, or parallel authoring syntax.

Component contract

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 contract

This is the component contract released with OINK 0.8.0. This page is the canonical English source; its Chinese peer is maintained beside it in content/docs/design/.

Tutorials and exhaustive examples belong in the reader-facing Components section. This page defines the API and behavior that those guides rely on.

Authoring model

Use ordinary Markdown when one block plus attributes can express a component. Use shortcodes for compound bodies or facts Markdown cannot carry. There is no parallel component registry. Native forms require:

Configuration model

Mon, 01 Jan 0001 00:00:00 +0000

Decision

OINK keeps Hugo’s native keys and useful Docsy-compatible keys in place, places theme presentation and behaviour under params.ui.*, and exposes a matching top-level front-matter key for a page override. It does not add a params.oink.* tree or a registry that shadows Hugo’s configuration model.

Context

OINK inherits a mature configuration surface and adds shells, content output, and local interaction. Earlier designs attempted to move every theme-owned key under a new namespace and resolve a complete configuration dictionary once per page. That produced a second language beside Hugo’s own keys, complicated section cascades, and made migration larger than the behaviour it was meant to control.

Consumer and migration evidence

Mon, 01 Jan 0001 00:00:00 +0000

Dated corpus snapshot

These counts describe the repositories inspected in August 2026. They are evidence for design choices, not live product metrics or compatibility promises.

Corpus

The authoring survey scanned the content/ trees of eleven OINK consumer sites: 5,325 Markdown files, of which 5,293 had YAML front matter. The set included single-language English and Chinese references, bilingual product sites, release archives, custom landing pages, and separate Book consumers.

Media convergence

Mon, 01 Jan 0001 00:00:00 +0000

Partially implemented

M1 (the shared media-result contract) and M2 (Landing resource metadata) are implemented on the theme’s main branch, and M3 is resolved as option 2: processing stays exclusively on native Markdown images, and the full fig source form remains a container whose parameter list deliberately excludes command/options. M4 (compatibility retirement) stays open pending a consumer inventory. The sections below are the original design record.

Current baseline

The content image hook, numbered fig, cards, and galleries resolve local page resources, section resources, global assets, static files, and explicit remote URLs through content/image-resolve.html. Raster resources can contribute intrinsic dimensions and processing derivatives. HTML Zoom eligibility is marked with data-td-image-zoom; the build-time detector only checks that theme-emitted marker.

OINK comprehensive review, 2026-08-26

Mon, 01 Jan 0001 00:00:00 +0000

Review snapshot, not a new contract

This page records evidence collected against github.com/pgsty/oink and its integration site on 2026-08-26. It changes no API and does not mean that any recommendation below is implemented. Current Design contracts, implementation, and owning checkers remain authoritative.

Superseded in part by OINK 0.7.1. The code findings F01–F06 were fixed in that release — see the 0.7.1 release notes. Read the findings below as the evidence that motivated the fix, not as the current state of the theme.

Bulk agent indexes

Mon, 01 Jan 0001 00:00:00 +0000

Implemented; ships with OINK 0.8.0

Accepted on 2026-08-27 after resolving every open decision. Both outputs – the per-top-level-section LLMSFULL bundles and the NAVJSON navigation tree at the language root – are implemented on the theme’s main branch and ship with OINK 0.8.0, after which this proposal retires; released behaviour is owned by the Architecture contract. OINK already shipped per-page Markdown, the in-language llms.txt, the HTML discovery link, and Copy Markdown; this page covers only the two new outputs.

Markdown-first authoring

Mon, 01 Jan 0001 00:00:00 +0000

Decision

Prefer a native Markdown form when Goldmark can preserve the intended semantics. Keep a shortcode only when it provides a capability the native form cannot express. Add a content scenario by extending an existing shell and data model, not by creating a parallel rendering system.

Context

OINK serves short manuals, large references, release archives, landing pages, and books. A survey of eleven consumer sites covered more than five thousand Markdown files and exposed both extremes: pages with almost no theme syntax and pages assembled from many nested shortcodes and local layout overrides.

Shell and navigation contract

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 contract

This is the shell and navigation contract released with OINK 0.8.0. This page is the canonical English source; its Chinese peer is maintained beside it in content/docs/design/.

Concern	Authority
Global navigation	Hugo `menus.main`
Docs / Book sidebar and pager	content tree or `data/docs_nav.json`
Root switcher	resolved top-level content roots
Discovery	per-language local search index
Page and Palette actions	shared action registry

No feature introduces another menu or page tree. One menu child level is interactive; deeper levels warn and flatten beneath linked group headings. External links use target="_blank" rel="noopener noreferrer"; internal links remain language- and subpath-aware.

Book publication pipeline

Mon, 01 Jan 0001 00:00:00 +0000

Draft proposal with implemented publication tooling

The opt-in BookManifest, the generic EPUB and PDF runners and their artifact validation are released, and the normative account of them is in Architecture. No build publishes either file on its own. What remains open here, and only here, is consumer migration.

Context and evidence

OINK already owns Book navigation order, numbered figures, tables, equations, examples, cross-references, whole-Book Print HTML, heading and footnote namespacing, and per-page Markdown degradation. The missing boundary is a machine-readable whole-Book handoff that a generic packager can consume.

Generated configuration schema

Mon, 01 Jan 0001 00:00:00 +0000

Decision

The two JSON Schemas under schema/ are projected by bin/generate-config-schema.py from the theme’s hugo.yaml and the template read-point scan; hand edits cannot survive CI. The schema is a read-only projection of the existing authorities, never a third one.

Context

The theme already has two configuration authorities: hugo.yaml, which declares every default beside a comment explaining it, and check-params.py, whose read-point scan knows every key the templates actually consume. Editors know neither, so authors type params.ui.* keys and front matter from memory.

Landing contract

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 contract

This is the landing-page contract released with OINK 0.8.0. This page is the canonical English source; its Chinese peer is maintained beside it in content/docs/design/.

Shared rules live in the architecture and component contracts; migration belongs in the migration contract.

Shell and data

Any regular page may declare layout: landing. It renders navbar, full-width canvas, and footer without docs sidebars or TOC rails. The homepage keeps data/home/<lang>.yaml as a compatible authoring path through the same renderer.

OINK migration boundary

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 contract

This is the migration contract released with OINK 0.8.0. This page is the canonical English source; its Chinese peer is maintained beside it in content/docs/design/.

This is source and configuration guidance, not a release ledger. Local source, commit, tag, push, consumer pin, deployment, and production parity remain separate states. For the reader-facing upgrade procedure, see Upgrade.

Toolkit scope

bin/migrations/oink06.py only scans and automatically rewrites Markdown files under a site’s content directory, including supported YAML front matter. It does not rewrite Hugo configuration, data files, layouts, assets, modules, or generated output. TOML/JSON front matter and ambiguous Markdown are reported with positions for manual review.

Design decisions

Mon, 01 Jan 0001 00:00:00 +0000

Accepted rationale

A decision explains why OINK chose one compatible design over another. The five contracts above it remain the normative description of current behaviour; implementation and owning checkers remain the executable facts.

OINK used to keep reviews, PRDs, and execution notes in a local plan/ directory. That made useful reasoning hard to discover and allowed abandoned designs to look authoritative. Accepted reasoning now lives here, in the same bilingual, versioned site as the contracts it supports.

Design and development

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 contract

This section publishes the maintainer contracts released with OINK 0.8.0, with Hugo Extended 0.160.1 as the compatibility floor. The canonical bilingual sources live in this repository under content/docs/design/.

This section is the durable design record for OINK. It complements the task-oriented guides elsewhere on the site: use those guides to build a site, and use this section to understand current invariants, the reasons behind them, the evidence used to evaluate alternatives, and work that is still only a proposal.

Design research

Mon, 01 Jan 0001 00:00:00 +0000

Evidence, not a contract

Research records what was measured, with which inputs and tool versions. Results may explain a decision, but they do not override the current contracts or implementation.

Research belongs in the public Design tree when another maintainer can inspect its method, understand its limits, and repeat the relevant check. Raw agent transcripts, temporary build logs, and local absolute paths do not meet that standard.

Design proposals and PRDs

Mon, 01 Jan 0001 00:00:00 +0000

Non-normative material

A proposal describes behaviour that may not exist. Current behaviour is defined by the contracts, accepted decisions, implementation, and owning checkers. Never use a proposal as a configuration reference.

This section is the canonical home for OINK product requirement documents, RFC-style designs, and unresolved maintainer proposals. Do not create a local plan/, plans/, proposal/, or parallel design tree in the theme repository or the documentation repository.

Design on OINK

Architecture contract

Repository and assembly

Warnings and safe fallbacks

Context

Goldmark block-attribute evidence

Method

Backlinks and knowledge graph

Premise

Component contract

Authoring model

Configuration model

Context

Consumer and migration evidence

Corpus

Media convergence

Current baseline

OINK comprehensive review, 2026-08-26

Bulk agent indexes

Markdown-first authoring

Context

Shell and navigation contract

Authorities and navigation

Book publication pipeline

Context and evidence

Generated configuration schema

Context

Landing contract

Shell and data

OINK migration boundary

Toolkit scope

Design decisions

Design and development

Design research

Design proposals and PRDs