OINK

Getting started

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

Oink is published as the Hugo Module github.com/pgsty/oink. A consuming site builds with Hugo Extended alone; Node.js, npm, PostCSS, and CDN-hosted browser packages are not part of the build contract.

Prerequisites

Install Git, Go, and Hugo Extended 0.160.1 or newer. The project site currently validates with 0.164.0:

git --version
go version
hugo version

The Hugo version output must include extended.

Add the module

From your Hugo site root, initialize a module if the site does not already have one, then pin an Oink release:

Architecture

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

Oink is a direct Hugo theme, not an application server or a runtime wrapper around Docsy. Hugo resolves content, configuration, layouts, and assets at build time, then emits a static site for any ordinary file host.

System boundary

flowchart LR
  C[Site content] --> H[Hugo Extended]
  G[Hugo configuration] --> H
  T[Oink Hugo Module] --> H
  V[Committed third-party assets] --> T
  H --> P[Static public directory]
  P --> B[Browser]

The consumer boundary starts with a site plus the resolved theme module and ends with Hugo’s static output. No JavaScript package manager, CSS postprocessor executable, or remote asset download is required in that path.

Local-first operation

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

OINK’s local-first rule is simple: a feature owned by the theme must not silently depend on a public CDN, a build-time download, or an unconfigured public service. A complete distribution can be built and its core pages browsed inside a network-isolated environment.

What local-first covers

The theme serves these dependencies from the generated site:

Capability	Local delivery
Shell and responsive UI	Bootstrap and OINK CSS/JavaScript
Icons and fonts	Font Awesome, Open Sans, Chakra Petch, IBM Plex Mono
Search	Lunr plus a CJK substring fallback and per-language indexes
Diagrams and formulae	Mermaid, KaTeX, and Markmap
API documentation	Swagger UI and Redoc
Rich content	Asciinema, ECharts, Infographic, and carousel runtime

Assets are committed under assets/ or static/. Hugo publishes them under the site’s baseURL, including subpath deployments.

Content components

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

OINK promotes the content components that proved reusable across PGSTY sites into the theme. Each component has a stable authoring API, unique instance IDs, local assets, and a defined safety boundary. Site-specific data widgets remain outside the theme.

Loading model

Interactive shortcodes mark the features used by a page. OINK then adds each required stylesheet or runtime once, even if the page has several component instances. A plain page does not download component code it never uses.

Configuration

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

OINK follows a “native first” configuration model. Site identity, languages, menus, outputs, taxonomies, markup, and modules stay in their Hugo-defined locations. Existing Docsy parameters remain where their semantics are useful. OINK adds only focused choices for behavior that cannot be inferred.

Configuration rules

Prefer Hugo configuration over a theme-specific duplicate.
Prefer an established Docsy parameter over an OINK synonym.
Put brand, content, repository, and UI choices in their semantic locations.
Keep internal vendor paths and template composition out of the public API.
Fail early for invalid values or a missing required endpoint.

There is no oink.enabled flag and no params.oink.* tree. Adding either would create a second theme mode and make every fix, test, and document ambiguous.

Deployment

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

OINK deployment has two separate stages: Hugo builds a complete public/ directory, then a static host publishes that directory. Keep build verification and hosted verification distinct so a successful local command is not mistaken for a completed production release.

Production build

Run the pinned Hugo Extended version from the site root:

hugo --gc --minify --cleanDestinationDir

--gc removes unused cached resources, --minify produces production assets, and --cleanDestinationDir removes files left by an earlier build. Review the command before using the last option when publishDir points anywhere other than the site’s dedicated output directory.

Migrating an existing site

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

OINK is intended to replace copied common shells, runtimes, and shortcodes without forcing a bulk rewrite of ordinary content. A safe migration removes overrides by dependency, keeps product-specific behavior in the site, and validates a temporary copy before changing production.

Migration principles

Pin the target implementation; do not migrate production to an unversioned branch.
Inventory overrides before deleting them.
Remove common theme copies, not the site’s business logic.
Preserve content URLs, front matter, and shortcode behavior where the OINK API is compatible.
Make unsafe or online exceptions explicit and temporary.
Test build output, browser behavior, and hosted behavior as separate layers.

Pin the target

Pin a published tag in go.mod or use the complete versioned archive. During pre-release evaluation, a Hugo Module site can use an ignored Go workspace to resolve a local checkout without editing the committed module version:

Release process

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

Oink treats implementation, validation, publication, and deployment as different states. A green local build is useful evidence, but it is not a public tag, a downloadable module, or a deployed documentation update.

Release states

State	Required evidence
Source complete	Scope, docs, changelog, attribution, and review are complete
Validated	Theme-module and project-site checks pass
Published	An immutable root tag exists in `pgsty/oink` and resolves through Go
Documented	`pgsty/oink.pgsty.com` pins and documents that tag
Deployed	The hosted documentation and target consumers pass verification

Report the exact state and evidence; do not call a local build a release.