This is the multi-page printable view of this section. .
Design research
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.
Research map
| Record | Evidence |
|---|---|
| Goldmark block attributes | Render-hook visibility and CommonMark container limits on the supported Hugo floor |
| Consumer and migration evidence | A dated corpus survey plus deterministic Book migration results |
Publication rules
A research record states its date, inputs, relevant versions, method, result, and known limits. Volatile counts are labeled as snapshots. External framework comparisons are refreshed from primary sources before publication and distilled into OINK-relevant conclusions rather than copied as a competitor catalogue.
When a result becomes a stable product choice, link it from an accepted decision. When it proposes behaviour that does not exist, move the design question to Proposals.
1 - Goldmark block-attribute evidence
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.
Each source shape was rendered with the compatibility-floor Hugo and the then current Hugo version. Relevant output was compared byte for byte. The findings below record platform behaviour, not visual styling.
Findings
| Source shape | Hook result | Design consequence |
|---|---|---|
Ordered list with paragraphs, fences, callouts, nested lists, and {.steps} |
The class attaches to the outer <ol> and rich list-item blocks survive |
A Markdown list is the native Steps form |
| Heading inside a list item | The heading remains inside <li> and enters .TableOfContents |
Native Steps can carry navigable headings |
Nested list with {.filetree} |
The class attaches to the outer <ul> |
FileTree needs no wrapper merely to preserve hierarchy |
Standalone image plus {#id num= caption= .class} |
render-image receives IsBlock=true and all attributes |
A Book figure can have a native image form |
| Inline image inside a paragraph | IsBlock=false; the image receives no block attributes |
Inline images cannot use the block-figure contract |
Block math plus {#id num=} |
render-passthrough receives block type and attributes |
A numbered equation can use the native passthrough form |
Table plus {.fields #id num= caption=} |
render-table receives the class and named attributes |
Field tables, matrix markers, captions, and Book numbering can share one hook |
Fenced code plus {#id num= caption=} |
The code-block hook receives the attributes | A numbered example can be the fence itself |
Callout plus {icon= tab=} |
The blockquote hook receives callout metadata and attributes | Folding, inline title markup, icon, and tab metadata can coexist |
| Attribute line separated from its block by a blank line | The attribute silently disappears | Source checks must reject orphan attribute lines |
Adjacent tables with tab= |
Each table hook receives its own tab label | Adjacent-block tabs can extend beyond code fences |
Container boundary
Hugo’s % shortcode delimiter renders .Inner as Markdown, but its template
must put a blank line before and after that inner Markdown. Without both blank
lines, a following list may be treated as literal HTML-block content instead of
Markdown.
A multi-line % container inside a CommonMark list item has a harder limit:
the generated HTML is not indented as list content, so the list closes before
the container and restarts afterwards. This is why OINK keeps a full Steps form
for steps that must contain another full container. Ordinary rich blocks,
fences, and < shortcodes do not have that limitation.
Nested % shortcodes also receive already rendered inner HTML in the relevant
collector shape. A collector that requires the child’s original Markdown uses
< delimiters and renders the captured body through the shared scoped block
renderer.
Attribute ownership
An available attribute is not automatically a public attribute. Every hook
owns a documented allowlist. style and inline on* handlers are rejected;
URL-bearing values pass the shared URL policy. A site class is retained only on
the surfaces where downstream CSS is an established extension mechanism.
The experiment also showed that gallery images inside list items can be block images while still receiving no knowledge of their parent list’s marker. A runtime may therefore need either a theme-emitted marker or a narrow structural fallback; it cannot assume the image hook sees arbitrary ancestors.
Limits and verification
These results cover Hugo 0.160.1 and 0.164.0 with the stated Goldmark settings. They do not promise identical behaviour for a site that changes those settings or for a later Hugo release. A Hugo-floor change reruns the focused component, Book, table, gallery, and Markdown-output checks before this snapshot is updated.
2 - Consumer and migration evidence
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.
The survey deliberately measured source Markdown rather than generated HTML. It counted shortcode calls, fenced-code attributes, callouts, table markers, raw HTML, front-matter keys, content types, and site-local layouts. A later Book-focused pass added five long-form consumers.
Findings that changed the design
| Evidence | Resulting choice |
|---|---|
| Content ranged from nearly plain Markdown to pages with many nested components | Native Markdown is the default form; a full form survives only for a named capability gap |
| Documentation, Blog, Landing, releases, and books repeatedly reimplemented navigation or cards locally | Extend the shared shell, registry, and primitive rather than adding a parallel system |
| Site-specific table classes were common, while canonical Field-table headings were rare | Hook attributes use an allowlist but preserve documented site-class extension points; Fields cannot be inferred from arbitrary two-column tables |
| Book sites carried private figure, table, equation, example, and cross-reference conventions | Numbered primitives and migration profiles need deterministic classification, stable IDs, and rendered-target verification |
| Sites mixed single-language, peer-file bilingual, and generated-language content | Language authority and generation boundaries must be explicit; a migration never treats an untracked generated tree as source |
| Rich HTML pages still needed print, Markdown, feeds, and agent output | Every component declares its output degradation before its interactive HTML is accepted |
The evidence also rejected several attractive additions. Documentation sites did not justify a second Landing system; Book sites did not need a new cover component; a serial archive did not justify a new shell type; and remote API collection belonged to site-side CI rather than a Hugo theme that promises local builds.
Block and table evidence
A focused pass over eleven sites plus Book consumers found 11,484 pipe tables.
Only eleven already matched the strict Field-table heading vocabulary, while
roughly 874 were reference-style tables and about 1,300 were compatibility
matrices. The result was explicit .fields and .matrix markers rather than
shape guessing.
The same pass found eighteen Steps blocks in the eleven-site corpus. They all
used the full form with headings and rich content. Platform probes showed that
a native ordered list could carry most of that content, while another full %
container inside a list item could not. OINK therefore keeps both forms for a
technical capability boundary, not merely for stylistic preference.
Deterministic Book migration
Three dated dry-run profiles tested whether the migration rules could account for every recognized source without inventing semantics:
| Profile snapshot | Classified result | Manual boundary |
|---|---|---|
| DDIA v2 | 106 figures, 3 tables, 22 code examples, and all 304 relevant links accounted for | One caption link flattened to visible text; no unaccounted skip |
| DDIA v1 | 90 numbered figures and 203 matching references | 14 decorative or unnumbered images deliberately left alone |
| TPME | 31 figures, 10 tables, 44 numbered references, and 1,018 generic stable references | No skipped recognized item |
| Private Book profile | 119 figures, 5 tables, and 136 numbered references | 3 ambiguous images retained for manual review |
Each profile was dry-run first, wrote only after its ambiguity boundary was understood, produced zero changes on a second run, built with warnings fatal, and passed rendered kind/number/anchor checks. The public migration toolkit and current profile boundaries are documented in Writing a book and the migration contract.
Limits
These counts should not be copied into product marketing or used as a current site inventory. Repeating the research requires a fresh repository list and a new dated report. Paths, uncommitted content, private repository names, raw agent transcripts, and generated build artifacts are intentionally excluded from this public record.