Update OINK

• 1: Update the OINK Hugo module
• 2: Migrate from the Docsy npm package
• 3: Update an OINK Git submodule or clone
• 4: Migrate a Docsy site to OINK

hugo version

hugo --gc --minify

1 - Update the OINK Hugo module

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:

go work init .
go work edit -replace=github.com/pgsty/oink=/absolute/path/to/oink
export HUGO_MODULE_WORKSPACE=go.work
hugo --gc --minify

Keep go.work out of version control rather than committing a developer-specific absolute path.

Verify the resolved module

Inspect Hugo’s dependency graph:

hugo mod graph

Confirm that the theme resolves to the intended tag, commit, or local replacement. No hugo mod npm pack or npm install step is required for OINK: browser dependencies already ship with the theme.

Continue with Review theme overrides.

2 - Migrate from the Docsy npm package

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.

Then remove @docsy/theme and any dependencies used only to build Docsy assets from the site’s package.json. Remove npm mounts for Bootstrap and Font Awesome from Hugo configuration, along with PostCSS and Autoprefixer build steps that exist only for the old theme pipeline.

Do not delete application dependencies merely because they use npm. The Hugo-only contract covers the documentation theme; a site-owned application or business component may have a separate, intentional toolchain.

Verify the migration

Build from a clean checkout with Hugo Extended and no node_modules directory:

hugo --gc --minify

Check LTR and RTL pages if the site supports both. Verify local fonts and icons, search, diagrams, API documentation, and any migrated content components. Once the build is clean, remove obsolete lockfiles only if no site-owned tooling uses them.

Continue with Review theme overrides.

3 - Update an OINK Git submodule or clone

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.

No npm installation is required. If the complete theme has nested source-only submodules for a particular release, initialize them according to that release’s notes; browser runtime assets in the OINK distribution are already present.

Update the clone

If the theme directory is a clone tracked or restored by the site, update it to the target ref:

git -C themes/oink fetch --tags
git -C themes/oink checkout THEME_REF

Commit, archive, or record the updated theme using the same reproducible method the site already uses. Do not leave production builds following main.

If the clone contains local changes, commit them on a branch before switching refs. Rebase or reapply them after the update and resolve conflicts explicitly. Prefer moving reusable changes upstream into OINK and keeping only true site-specific overrides in the consuming site.

Continue with Review theme overrides.

4 - Migrate a Docsy site to OINK

This migration removes copied common shell overrides and the consumer-side npm asset pipeline. It does not require a bulk rewrite of Markdown content.

Before you begin

Create a branch and make sure the existing site builds. Inventory custom files under layouts/, assets/, static/, and i18n/, classifying each as:

• common Docsy shell code now supplied by OINK;
• a reusable component now supplied by OINK;
• a site-owned brand, product page, or business component that must remain.

Do not delete the third category.

Select a theme distribution

Choose a pinned Git checkout, versioned archive, complete offline distribution, or the public Oink Hugo Module. For a temporary local rehearsal, import Oink and use a Go workspace to resolve a local checkout:

go work init .
go work edit -replace=github.com/pgsty/oink=/absolute/path/to/oink
export HUGO_MODULE_WORKSPACE=go.work
hugo --gc --minify

This tests OINK without publishing a developer-specific path in site config or go.mod.

Remove the consumer asset pipeline

Delete npm mounts and build steps used only to source Bootstrap, Font Awesome, fonts, or theme browser runtimes. Remove postCSS calls and Autoprefixer steps that exist only for Docsy. Keep package.json when site-owned software still needs it, but the documentation build itself must succeed without installing those packages.

Remove common overrides

OINK directly provides the docs and blog shell, navbar, footer, sidebar, table of contents, search, language selector, head assets, and core content components. Remove matching site overrides one dependency group at a time.

Keep custom homepages, portals, download pages, product data, and business shortcodes until they have an explicit replacement. See the migration guide for the detailed delete/keep matrix.

Verify the result

From a clean checkout with Hugo Extended available, run:

hugo --gc --minify

Check the bilingual page set, local search, dark mode, mobile navigation, print output, diagrams, API docs, content components, and site-specific pages. Inspect the browser network log to confirm that default theme resources are same-origin.

Only after the migrated build and visual review pass should you remove obsolete configuration, lockfiles, or workflow steps.