Skip to content

Design and development

OINK’s contracts, accepted decisions, dated research, and active proposals in one bilingual section.
OINK 1.5.1 contract

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.