Upgrade on OINK

Upgrade the Oink Hugo Module

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

Pin a version

Production sites should import a release tag or immutable commit, never an unversioned branch. From the site root, update Oink to a specific ref:

hugo mod get github.com/pgsty/oink@THEME_REF
hugo mod tidy

Replace THEME_REF with the published root tag or commit named by the release.

Test a local checkout

To test the current OINK checkout without changing the committed module path, use an ignored Go workspace with the local theme checkout:

Upgrade an Oink Git submodule or clone

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

Use the procedure matching the installation: submodule or clone. Pin the target release tag or immutable commit in both cases.

Update the submodule

From the site root, fetch tags inside the theme and check out the target ref:

git -C themes/oink fetch --tags
git -C themes/oink checkout THEME_REF
git add themes/oink
git commit -m "Update OINK theme to THEME_REF"

Replace themes/oink if the site uses another directory name. The parent repository records the resulting submodule commit. Push that parent commit so CI and other contributors resolve the same source.

Migrate from the Docsy npm package

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

The upstream @docsy/theme npm package is not an OINK distribution channel. OINK ships Bootstrap, Font Awesome, fonts, and browser runtimes directly with the theme so that consumer sites build with Hugo Extended alone.

Remove the npm theme integration

First select an OINK distribution: a versioned archive, Git submodule or clone, or the compatibility Hugo module. Make that theme available to Hugo and confirm that hugo --gc --minify can resolve it.

Migrate an existing Docsy 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: