Design and development 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.

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:

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.

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 and development on OINK

Architecture contract

Repository and assembly

Component contract

Authoring model

Shell and navigation contract

Authorities and navigation

Landing contract

Shell and data

OINK migration boundary

Toolkit scope