Design and development
This contract describes OINK v1.3.1. Theme development uses the sibling checkout; release acceptance verifies the published module with replacements and workspaces disabled. Consumer adoption and deployment have their own checks.
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.
Reading this section
| Layer | Meaning |
|---|---|
| Contracts | Normative behavior that compatible implementations must preserve |
| Decisions | Accepted rationale and boundaries that explain current behavior |
| Research | Dated, non-normative evidence that may need to be refreshed |
| Proposals | Draft PRDs and RFCs; publication here is not proof of implementation |
Contract map
| Contract | Authority |
|---|---|
| Architecture | Build, configuration, diagnostics, localization, featured images, output, security, accessibility, and performance |
| Components | Component API, Book and release primitives, validation, and output degradation |
| Shell and navigation | Navigation, search, blog presentation, actions, taxonomies, and page-end composition |
| Landing pages | Landing data, the 22-section registry, runtime, accessibility, and outputs |
| Migration boundary | Supported 0.4-to-current content and configuration migrations |
Design records
| Collection | Contents |
|---|---|
| Decisions | Accepted diagnostic, configuration, authoring, Expo, and CLI rationale |
| Research | Goldmark probes, consumer evidence, CLI acceptance, and October theme reviews |
| Proposals | Active PRDs for knowledge graphs, media convergence, visual presets, and the CLI roadmap |
Create every new OINK PRD or RFC as an English and Chinese page pair under
content/docs/design/proposals/. Do not create another repository-local
plan/, plans/, or proposal/ tree. Once a proposal is accepted, update the
implementation, owning checker, and relevant contract; preserve the stable
rationale under Decisions and retire the draft through Git history and the
changelog.
Expo contract
The Expo contract describes the image-album layout introduced in OINK 1.3.0. Its accepted decision records the content model and the revisions to the earlier Muse experiment. The authoring guide explains album setup and viewer controls. The contract, accepted decision, and authoring guide describe the same released content model and controls.
Authority and maintenance
This directory owns the maintainer design prose in English and Chinese. The theme
repository owns executable facts: hugo.yaml owns published defaults; owning
resolvers and checkers define optional shapes; layouts/ and assets/ own
rendered behavior; check scripts and tests/goldens/ own validation; and
VENDOR.json owns bundled versions, licenses, files, and checksums.
Whenever public behavior changes, update the implementation, its owning checker, and both language versions of the relevant contract in the same delivery. Tests should exercise behavior and output rather than pinning prose.