Design and development
The contracts in this section describe OINK v1.5.1. Theme development uses the sibling checkout; release acceptance verifies the published module with replacements and workspaces disabled.
This section explains how OINK works and why it has its present shape. It brings together current contracts, the reasoning behind accepted decisions, evidence from alternative designs, and ideas that remain proposals. The other guides on this site explain how to build and maintain a site with OINK.
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 each 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. After acceptance, update the
implementation, its checker, and the applicable contract, then record the
accepted rationale under Decisions. Retire the draft from active use while
preserving it in 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 English and Chinese design text for maintainers; the
theme repository owns the executable facts. Within the theme, hugo.yaml
defines published defaults, while each resolver and checker defines the input
shapes it accepts. layouts/ and assets/ define rendered behavior, and check
scripts with tests/goldens/ define validation. VENDOR.json records bundled
versions, licenses, files, and checksums.
When public behavior changes, update the implementation, its checker, and both language versions of the applicable contract in the same delivery. Tests should check behavior and output without requiring exact prose.