Skip to content

Design

49 pages
  • Give large tables room to read

    In Research

    Design

    Historical research; see the 1.4.0 decision Research date: 2026-10-26. This study informed the table-reading design in OINK 1.4.0. The accepted decision and table guide describe the released behavior and supersede the entrance and scope …

    Historical research; see the 1.4.0 decision Research date: 2026-10-26. This study informed the table-reading design in OINK 1.4.0. The accepted decision and table guide describe the released behavior and supersede the entrance and scope …

  • Unified diagram reading

    In Decisions

    Design

    Accepted in OINK 1.4.0 Shared diagram viewing, source export and demand loading ship in 1.4.0. Components, Architecture and browser printing own the behavior. Context Before this change, Mermaid had a pan/zoom dialog but loads its engine at page …

    Accepted in OINK 1.4.0 Shared diagram viewing, source export and demand loading ship in 1.4.0. Components, Architecture and browser printing own the behavior. Context Before this change, Mermaid had a pan/zoom dialog but loads its engine at page …

  • OINK 1.3.2 and Hugo 0.168 consumer inventory

    In Research

    Design

    This dated inventory records local checkouts under ~/pgsty and ~/www. The current build policy is owned by the architecture contract and diagnostics decision. Baseline OINK v1.3.2 was published on 2026-10-18 at 13:37 UTC. Its tag resolves to …

    This dated inventory records local checkouts under ~/pgsty and ~/www. The current build policy is owned by the architecture contract and diagnostics decision. Baseline OINK v1.3.2 was published on 2026-10-18 at 13:37 UTC. Its tag resolves to …

  • Local search refinement

    In Decisions

    Design

    Accepted in OINK 1.4.0 Owner: OINK maintainers. Affected contract: Shell. This search behavior ships in OINK 1.4.0. Evidence and scope The previous CJK path required one contiguous query in one field. English uses Lunr, and both return page links …

    Accepted in OINK 1.4.0 Owner: OINK maintainers. Affected contract: Shell. This search behavior ships in OINK 1.4.0. Evidence and scope The previous CJK path required one contiguous query in one field. English uses Lunr, and both return page links …

  • Design proposals and PRDs

    In Proposals

    Design

    Non-normative material A proposal describes behavior that may not exist. The contracts, accepted decisions, implementation, and owning checkers define current behavior. Never use a proposal as a configuration reference. This section contains the …

    Non-normative material A proposal describes behavior that may not exist. The contracts, accepted decisions, implementation, and owning checkers define current behavior. Never use a proposal as a configuration reference. This section contains the …

  • Theme review, 2026-10-13

    In Research

    Design

    Local review snapshot This record describes local source and tests against the v1.2.0 consumer baseline. Scope The review began at theme commit f8f476e, with existing consumer-maintenance and compact-sidebar changes and an ongoing English …

    Local review snapshot This record describes local source and tests against the v1.2.0 consumer baseline. Scope The review began at theme commit f8f476e, with existing consumer-maintenance and compact-sidebar changes and an ongoing English …

  • OINK 1.5.1 readiness review, 2026-11-06

    In Research

    Design

    Local repair acceptance complete The three reproduced regressions below have been repaired in the working trees and the targeted, theme, site, and browser checks pass. This dated review does not announce a release, consumer upgrade, or deployment. …

    Local repair acceptance complete The three reproduced regressions below have been repaired in the working trees and the targeted, theme, site, and browser checks pass. This dated review does not announce a release, consumer upgrade, or deployment. …

  • Translation comparison

    In Decisions

    Design

    Accepted in OINK 1.5.0 This decision records the released params.ui.compare translation reader. The shell contract defines the reader and its controls. The architecture contract defines the browser boundary. The multilingual guide gives site setup; …

    Accepted in OINK 1.5.0 This decision records the released params.ui.compare translation reader. The shell contract defines the reader and its controls. The architecture contract defines the browser boundary. The multilingual guide gives site setup; …

  • Design research

    In Research

    Design

    Dated research records Research records capture measurements, inputs, and tool versions from specific studies. Current behavior is defined by the Design contracts and validated on Hugo Extended 0.168.0 per the toolchain contract. Publish research in …

    Dated research records Research records capture measurements, inputs, and tool versions from specific studies. Current behavior is defined by the Design contracts and validated on Hugo Extended 0.168.0 per the toolchain contract. Publish research in …

  • Ink and Terminal need reading acceptance

    In Research

    Design

    Pre-release research snapshot (2026-10-26) This record preserves inputs and measurements from before the OINK 1.4.0 release preparation. At 320px with a 32px root/default font, footer links cause document overflow across all four presets. Ink and …

    Pre-release research snapshot (2026-10-26) This record preserves inputs and measurements from before the OINK 1.4.0 release preparation. At 320px with a 32px root/default font, footer links cause document overflow across all four presets. Ink and …

  • Design and development

    In Design

    Design

    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 …

    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 …

  • Review repairs, 2026-11-06

    In Research

    Design

    Development evidence This record describes local changes after v1.5.0. It does not establish a new release, consumer upgrade, or deployment. The original review’s roughly 170 entries have not all been accepted or fixed. Inputs and method The review …

    Development evidence This record describes local changes after v1.5.0. It does not establish a new release, consumer upgrade, or deployment. The original review’s roughly 170 entries have not all been accepted or fixed. Inputs and method The review …

  • Explicit table reading

    In Decisions

    Design

    Accepted in OINK 1.4.0 This decision records the released .expand table-reader behavior. The component contract defines the behavior. The table guide gives author syntax; the dated research retains the earlier comparisons. Context Most documentation …

    Accepted in OINK 1.4.0 This decision records the released .expand table-reader behavior. The component contract defines the behavior. The table guide gives author syntax; the dated research retains the earlier comparisons. Context Most documentation …

  • Component refinement, 2026-10-25

    In Research

    Design

    Local acceptance record Phases 0–3 and final acceptance in phase 5 are complete for this component change. The moving selection trial remains deferred. Inputs and method The final review used isolated sibling checkouts based on theme 7f9589f and …

    Local acceptance record Phases 0–3 and final acceptance in phase 5 are complete for this component change. The moving selection trial remains deferred. Inputs and method The final review used isolated sibling checkouts based on theme 7f9589f and …

  • Blog posts as a gallery

    In Decisions

    Design

    Accepted in OINK 1.4.0 This decision records the released gallery blog view and its compatibility boundaries. The shell contract defines the behavior. The design blog explains the reading experience, and the authoring guide gives configuration. …

    Accepted in OINK 1.4.0 This decision records the released gallery blog view and its compatibility boundaries. The shell contract defines the behavior. The design blog explains the reading experience, and the authoring guide gives configuration. …

  • Stabilizing Ink and Terminal for reading

    In Proposals

    Design

    Draft — promotion blocked Enlarged text overflows the shared footer. At 320px with a 32px root/default font, English Ink reaches 424px document width and Terminal 408px. The comparison overlay does not repair this shared failure. Neither prototype …

    Draft — promotion blocked Enlarged text overflows the shared footer. At 320px with a 32px root/default font, English Ink reaches 424px document width and Terminal 408px. The comparison overlay does not repair this shared failure. Neither prototype …

  • Expo image collections

    In Decisions

    Design

    Available in OINK 1.3.0 Expo is included in OINK v1.3.0. The Expo contract defines required behavior. The authoring guide explains how to create an album. Context Docs organizes explanations. Blog organizes posts. Book organizes chapters. Expo …

    Available in OINK 1.3.0 Expo is included in OINK v1.3.0. The Expo contract defines required behavior. The authoring guide explains how to create an album. Context Docs organizes explanations. Blog organizes posts. Book organizes chapters. Expo …

  • Design decisions

    In Decisions

    Design

    Accepted rationale A decision explains why OINK selected one compatible design instead of another. The five contracts define the required current behavior. The implementation and its checkers define the executable facts. OINK previously kept …

    Accepted rationale A decision explains why OINK selected one compatible design instead of another. The five contracts define the required current behavior. The implementation and its checkers define the executable facts. OINK previously kept …

  • CLI acceptance snapshot, 2026-09-29

    In Research

    Design

    Historical CLI acceptance snapshot (2026-09-29) This page records the 2026-09-29 validation of the local 0.1.0-dev CLI candidate at commit e623d93. Current CLI behavior is defined in the CLI and result contract. Inputs and method The CLI belongs to …

    Historical CLI acceptance snapshot (2026-09-29) This page records the 2026-09-29 validation of the local 0.1.0-dev CLI candidate at commit e623d93. Current CLI behavior is defined in the CLI and result contract. Inputs and method The CLI belongs to …

  • Document comparison research, 2026-10-29

    In Research

    Design

    Historical research; see the 1.5.0 decision Research date: 2026-10-29. This bounded source review of OINK v1.4.0 informed the translation reader in OINK 1.5.0. The accepted decision and the shell contract describe the released behavior and supersede …

    Historical research; see the 1.5.0 decision Research date: 2026-10-29. This bounded source review of OINK v1.4.0 informed the translation reader in OINK 1.5.0. The accepted decision and the shell contract describe the released behavior and supersede …

  • CLI maintenance acceptance on 2026-10-03: R6–R8 and A18

    In Research

    Design

    Part of the CLI maintenance acceptance record These R6–R8 and A18 sections of the dated record were moved here unchanged on 2026-11-06 so each page stays small enough to read whole. The scope, evidence rules, case ledger and delivery state remain on …

    Part of the CLI maintenance acceptance record These R6–R8 and A18 sections of the dated record were moved here unchanged on 2026-11-06 so each page stays small enough to read whole. The scope, evidence rules, case ledger and delivery state remain on …

  • CLI maintenance acceptance on 2026-10-03: R1–R5

    In Research

    Design

    Part of the CLI maintenance acceptance record These R1–R5 sections of the dated record were moved here unchanged on 2026-11-06 so each page stays small enough to read whole. The scope, evidence rules, case ledger and delivery state remain on the …

    Part of the CLI maintenance acceptance record These R1–R5 sections of the dated record were moved here unchanged on 2026-11-06 so each page stays small enough to read whole. The scope, evidence rules, case ledger and delivery state remain on the …

  • CLI maintenance acceptance on 2026-10-03

    In Research

    Design

    Historical CLI maintenance acceptance ledger (2026-10-03 to 2026-10-04) This record preserves the initial audit, intermediate trials, and local R1–R8 and A18 runtime/archive acceptance for the CLI maintenance roadmap. On 2026-10-04, the CLI surface …

    Historical CLI maintenance acceptance ledger (2026-10-03 to 2026-10-04) This record preserves the initial audit, intermediate trials, and local R1–R8 and A18 runtime/archive acceptance for the CLI maintenance roadmap. On 2026-10-04, the CLI surface …

  • Paper and Slate visual presets

    In Decisions

    Design

    OINK 1.2.0 Paper and Slate ship in 1.2.0. Ink and Terminal are included as explicit opt-ins; their remaining design work is recorded below. Decision Paper is the default, with warm paper/ink colors, blue links, IBM Plex Sans, heading hairlines and …

    OINK 1.2.0 Paper and Slate ship in 1.2.0. Ink and Terminal are included as explicit opt-ins; their remaining design work is recorded below. Decision Paper is the default, with warm paper/ink colors, blue links, IBM Plex Sans, heading hairlines and …

  • OINK migration boundary

    In Design

    Design

    OINK 1.5.1 contract This contract describes OINK v1.5.1. This page defines the maintainer migration toolkit and configuration boundaries. See Upgrade for the reader-facing upgrade guide. Toolkit scope bin/migrations/oink06.py scans and automatically …

    OINK 1.5.1 contract This contract describes OINK v1.5.1. This page defines the maintainer migration toolkit and configuration boundaries. See Upgrade for the reader-facing upgrade guide. Toolkit scope bin/migrations/oink06.py scans and automatically …

  • Component refinement across four visual presets

    In Decisions

    Design

    Accepted in OINK 1.4.0 Shared component styling and three optional presentation variants ship in 1.4.0. The component contract owns their behavior; the comparison guide shows them together. Context Cards, disclosures, Tabs and code controls had …

    Accepted in OINK 1.4.0 Shared component styling and three optional presentation variants ship in 1.4.0. The component contract owns their behavior; the comparison guide shows them together. Context Cards, disclosures, Tabs and code controls had …

  • Optional CLI and result contract

    In Decisions

    Design

    Current scope; local candidate This contract describes the reduced local 0.1.0-dev command surface on 2026-10-04. Keep site diagnosis, real Hugo checks, initialization, builds, upgrades, and guarded maintenance plans. Cobra provides command help; …

    Current scope; local candidate This contract describes the reduced local 0.1.0-dev command surface on 2026-10-04. Keep site diagnosis, real Hugo checks, initialization, builds, upgrades, and guarded maintenance plans. Cobra provides command help; …

  • OINK 1.1 release review, 2026-09-20

    In Research

    Design

    Historical release review (2026-09-20) This record captures the pre-release validation and five runtime fixes for OINK 1.1, followed by the v1.1.0 publication record. Scope and baseline The review starts at theme commit …

    Historical release review (2026-09-20) This record captures the pre-release validation and five runtime fixes for OINK 1.1, followed by the v1.1.0 publication record. Scope and baseline The review starts at theme commit …

  • Expo layout contract

    In Design

    Design

    OINK 1.5.1 contract This contract describes OINK v1.5.1. This page defines required behavior. Use Expo albums to create content. Read the design decision for the reasons behind this model. Content and navigation type: expo selects the album layout. …

    OINK 1.5.1 contract This contract describes OINK v1.5.1. This page defines required behavior. Use Expo albums to create content. Read the design decision for the reasons behind this model. Content and navigation type: expo selects the album layout. …

  • Visual presets and appearance switching

    In Proposals

    Design

    Phase 1 released in 1.2.0; Ink/Terminal opt-ins available Paper, Slate and the Appearance menu ship with OINK 1.2.0. The architecture contract, accepted decision and acceptance record own phase-one behavior and evidence. A subsequent Ink/Terminal …

    Phase 1 released in 1.2.0; Ink/Terminal opt-ins available Paper, Slate and the Appearance menu ship with OINK 1.2.0. The architecture contract, accepted decision and acceptance record own phase-one behavior and evidence. A subsequent Ink/Terminal …

  • Landing contract

    In Design

    Design

    OINK 1.5.1 contract This contract describes OINK v1.5.1. The architecture and component contracts define shared rules. The migration contract defines migration rules. Shell and data Any regular page may use layout: landing. It renders the navbar, a …

    OINK 1.5.1 contract This contract describes OINK v1.5.1. The architecture and component contracts define shared rules. The migration contract defines migration rules. Shell and data Any regular page may use layout: landing. It renders the navbar, a …

  • Generated configuration schema

    In Decisions

    Design

    Decision bin/generate-config-schema.py generates the two JSON Schemas under schema/. It reads the theme’s hugo.yaml and the template read-point scan. CI rejects manual schema changes. The schemas are read-only projections of the existing …

    Decision bin/generate-config-schema.py generates the two JSON Schemas under schema/. It reads the theme’s hugo.yaml and the template read-point scan. CI rejects manual schema changes. The schemas are read-only projections of the existing …

  • Community issue and PR review, 2026-09-19

    In Research

    Design

    Historical review snapshot (2026-09-19) This page records source inspection, GitHub status, local builds, and targeted browser observations from 2026-09-19, followed by the same-day implementation and acceptance follow-up. The initial review remains …

    Historical review snapshot (2026-09-19) This page records source inspection, GitHub status, local builds, and targeted browser observations from 2026-09-19, followed by the same-day implementation and acceptance follow-up. The initial review remains …

  • OINK CLI maintenance roadmap

    In Proposals

    Design

    Implemented requirements record This dated requirements record preserves the original R1–R8 planning scope and anchors. Current CLI behavior belongs to the CLI contract and CLI introduction, and historical acceptance evidence belongs to the …

    Implemented requirements record This dated requirements record preserves the original R1–R8 planning scope and anchors. Current CLI behavior belongs to the CLI contract and CLI introduction, and historical acceptance evidence belongs to the …

  • Shell and navigation contract

    In Design

    Design

    OINK 1.5.1 contract This contract describes OINK v1.5.1. Authorities and navigation 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 …

    OINK 1.5.1 contract This contract describes OINK v1.5.1. Authorities and navigation 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 …

  • Markdown-first authoring

    In Decisions

    Design

    Decision If Goldmark can preserve the intended meaning, prefer a native Markdown form. Keep a shortcode only when the native form cannot provide its capability. For a new content scenario, extend an existing shell and data model. Do not create a …

    Decision If Goldmark can preserve the intended meaning, prefer a native Markdown form. Keep a shortcode only when the native form cannot provide its capability. For a new content scenario, extend an existing shell and data model. Do not create a …

  • OINK CLI and the next product stage

    In Proposals

    Design

    Local first-stage candidate; later roadmap remains draft The independent Go repository pgsty/oink-cli and first-stage development were authorized on 2026-09-29. Its six commands now have a local 0.1.0-dev implementation, with final local acceptance …

    Local first-stage candidate; later roadmap remains draft The independent Go repository pgsty/oink-cli and first-stage development were authorized on 2026-09-29. Its six commands now have a local 0.1.0-dev implementation, with final local acceptance …

  • OINK comprehensive review, 2026-08-26

    In Research

    Design

    Historical review snapshot (2026-08-26) This page records the 2026-08-26 audit of github.com/pgsty/oink and its integration site. OINK 0.7.1 subsequently fixed code findings F01–F06 (see the 0.7.1 release notes). Current behavior is defined by the …

    Historical review snapshot (2026-08-26) This page records the 2026-08-26 audit of github.com/pgsty/oink and its integration site. OINK 0.7.1 subsequently fixed code findings F01–F06 (see the 0.7.1 release notes). Current behavior is defined by the …

  • Media convergence

    In Proposals

    Design

    Partially implemented The theme’s main branch implements M1 (the shared media-result contract) and M2 (Landing resource metadata). M3 is resolved as option 2. Only native Markdown images support processing. The full fig source form remains a …

    Partially implemented The theme’s main branch implements M1 (the shared media-result contract) and M2 (Landing resource metadata). M3 is resolved as option 2. Only native Markdown images support processing. The full fig source form remains a …

  • Consumer and migration evidence

    In Research

    Design

    Dated corpus snapshot These counts describe repositories inspected in August 2026 to inform OINK’s shell, component, and Book migration design. Corpus The authoring survey scanned the content/ trees of eleven OINK consumer sites and found 5,325 …

    Dated corpus snapshot These counts describe repositories inspected in August 2026 to inform OINK’s shell, component, and Book migration design. Corpus The authoring survey scanned the content/ trees of eleven OINK consumer sites and found 5,325 …

  • Configuration model

    In Decisions

    Design

    Decision OINK retains Hugo’s native keys and useful Docsy-compatible keys. Theme presentation and behavior use params.ui.*. A page override uses the matching top-level front-matter key. OINK does not add a params.oink.* tree or a second registry for …

    Decision OINK retains Hugo’s native keys and useful Docsy-compatible keys. Theme presentation and behavior use params.ui.*. A page override uses the matching top-level front-matter key. OINK does not add a params.oink.* tree or a second registry for …

  • Component contract

    In Design

    Design

    OINK 1.5.1 contract This contract describes OINK v1.5.1. The reader-facing Components section provides tutorials and complete examples. This page defines the API and behavior used by those guides. Authoring model Use ordinary Markdown when one block …

    OINK 1.5.1 contract This contract describes OINK v1.5.1. The reader-facing Components section provides tutorials and complete examples. This page defines the API and behavior used by those guides. Authoring model Use ordinary Markdown when one block …

  • Visual preset acceptance, 2026-10-05

    In Research

    Design

    Local verification record This record covers sibling-checkout theme output for the Paper and Slate presets prior to tagging v1.2.0. Inputs Theme and documentation working trees on 2026-10-05; Hugo Extended 0.166.0, Go 1.27.1, Node 26.9.0, and …

    Local verification record This record covers sibling-checkout theme output for the Paper and Slate presets prior to tagging v1.2.0. Inputs Theme and documentation working trees on 2026-10-05; Hugo Extended 0.166.0, Go 1.27.1, Node 26.9.0, and …

  • OINK 1.2 pre-release review, 2026-10-05

    In Research

    Design

    Local candidate review This review covers the October 5 working trees prior to tagging v1.2.0. The public theme tag and the documentation site’s consumer pin were still v1.1.0 at review time. Scope and inputs The theme starts at a1979a4 and the …

    Local candidate review This review covers the October 5 working trees prior to tagging v1.2.0. The public theme tag and the documentation site’s consumer pin were still v1.1.0 at review time. Scope and inputs The theme starts at a1979a4 and the …

  • Ink and Terminal experiment, 2026-10-05

    In Research

    Design

    Local experiment record Ink and Terminal compile into the theme stylesheet and use the Appearance control. They remain explicitly enabled experiments, pending design acceptance. Inputs and method This extends the Paper/Slate implementation on the …

    Local experiment record Ink and Terminal compile into the theme stylesheet and use the Appearance control. They remain explicitly enabled experiments, pending design acceptance. Inputs and method This extends the Paper/Slate implementation on the …

  • Backlinks and knowledge graph

    In Proposals

    Design

    G1 implemented; G2/G3 remain draft On 2026-08-27, all G1 open decisions were resolved and G1 (static backlinks) was accepted. The theme’s main branch implements G1, which is included in OINK 0.8.0. The local and global graphs (G2/G3) remain drafts …

    G1 implemented; G2/G3 remain draft On 2026-08-27, all G1 open decisions were resolved and G1 (static backlinks) was accepted. The theme’s main branch implements G1, which is included in OINK 0.8.0. The local and global graphs (G2/G3) remain drafts …

  • Goldmark block-attribute evidence

    In Research

    Design

    Verified snapshot These probes produced identical relevant output bytes on Hugo Extended 0.160.1 and 0.164.0. They explain OINK’s native component forms. The current component contract defines required behavior. Method The probe used a minimal Hugo …

    Verified snapshot These probes produced identical relevant output bytes on Hugo Extended 0.160.1 and 0.164.0. They explain OINK’s native component forms. The current component contract defines required behavior. Method The probe used a minimal Hugo …

  • Warnings and safe fallbacks

    In Decisions

    Design

    Decision OINK does not call Hugo’s errorf. Invalid author or site input produces a warning. OINK then uses a documented safe fallback or omits the invalid fragment. Development, CI, release, and deployment use Hugo Extended 0.168.0 without …

    Decision OINK does not call Hugo’s errorf. Invalid author or site input produces a warning. OINK then uses a documented safe fallback or omits the invalid fragment. Development, CI, release, and deployment use Hugo Extended 0.168.0 without …

  • Architecture contract

    In Design

    Design

    OINK 1.5.1 contract This contract describes OINK v1.5.1. Hugo toolchain Use OINK v1.5.1 and Hugo Extended 0.168.0 for maintained sites, development, CI, and release validation. Keep this toolchain pinned. Do not enable --panicOnWarning or …

    OINK 1.5.1 contract This contract describes OINK v1.5.1. Hugo toolchain Use OINK v1.5.1 and Hugo Extended 0.168.0 for maintained sites, development, CI, and release validation. Keep this toolchain pinned. Do not enable --panicOnWarning or …