Design decisions on OINK

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.

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.

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.

Generated configuration schema

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

Decision

The two JSON Schemas under schema/ are projected by bin/generate-config-schema.py from the theme’s hugo.yaml and the template read-point scan; hand edits cannot survive CI. The schema is a read-only projection of the existing authorities, never a third one.

Context

The theme already has two configuration authorities: hugo.yaml, which declares every default beside a comment explaining it, and check-params.py, whose read-point scan knows every key the templates actually consume. Editors know neither, so authors type params.ui.* keys and front matter from memory.