Design on OINK

Architecture contract

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

OINK 0.6.0 contract

This is the architecture contract released with OINK 0.6.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

Draft PRD — not implemented

OINK currently has no backlink block, local graph, global graph page, or graph output format. Names and configuration in this proposal are not public API until the proposal is accepted and the contracts change.

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.6.0 contract

This is the component contract released with OINK 0.6.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

Draft PRD — remaining work only

OINK already has a shared content-image resolver, one Zoom marker, processed Markdown images, numbered figures, and safe Landing URL handling. This page proposes only the unresolved convergence; it must not be read as a list of missing current features.

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.

Bulk agent indexes

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

Draft PRD — partial premise already exists

OINK already supports per-page Markdown, language-local llms.txt, HTML discovery links, and Copy Markdown. It does not currently publish llms-full.txt or a navigation JSON. Only those remaining outputs are proposed here.

Current baseline

A site opts into Hugo’s Markdown output for pages and sections and the LLMS home output for llms.txt. OINK renders shortcodes into semantic Markdown, keeps the source URL and language-local LLMS index discoverable, and derives Copy Markdown from the same alternative output URL. The theme declares output formats but does not force a site’s outputs selection.

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.6.0 contract

This is the shell and navigation contract released with OINK 0.6.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.6.0 contract

This is the landing-page contract released with OINK 0.6.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.6.0 contract

This is the migration contract released with OINK 0.6.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.6.0 contract

This section publishes the maintainer contracts released with OINK 0.6.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

Bulk agent indexes

Current baseline

Markdown-first authoring

Context

Shell and navigation contract

Authorities and navigation

Landing contract

Shell and data

OINK migration boundary

Toolkit scope

Design decisions

Design and development

Design research

Design proposals and PRDs