Upgrade

• 1: Upgrade the Oink Hugo Module
• 2: Upgrade an Oink Git submodule or clone
• 3: Migrate from the Docsy npm package
• 4: Migrate an existing Docsy site

hugo version

hugo --gc --minify

1 - Upgrade 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 - Upgrade 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.

3 - 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.

4 - Migrate an existing Docsy site

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:

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

The site’s hugo.yaml imports github.com/pgsty/oink; the workspace substitutes only the local checkout.

Inventory existing overrides

Group each site-level file into one of four classes:

Search layouts/, assets/, static/, configuration, and build workflows together. A copied shortcode often has a matching JavaScript bundle, stylesheet, vendor file, and CI install step.

Move configuration

Search and brand

Enable theme-owned local search and point the shell at the site’s own logo:

params:
  logo: img/product.svg
  offlineSearch: true

Continue using title, languages.*, github_repo, github_project_repo, github_branch, page_width, and ui.* in their existing semantic locations. Do not migrate values into an oink.* namespace.

Fonts

The legacy Sass switch $td-enable-google-fonts: true now selects the local Open Sans files shipped by OINK; it no longer requests Google Fonts. $td-web-font-path is not part of the current build. A site that needs another font must provide approved local assets and their licenses.

Remove common overrides

After a temporary build proves equivalence, remove site copies of:

• layouts/baseof.html and common docs/blog baseof*.html files;
• common navbar, footer, sidebar, table-of-contents, search, head-CSS partials, and their hooks;
• old common branded documentation-shell partials;
• asciinema, echarts, infographic, doc-carousel, details, tab/tabpane, card, and param shortcode copies;
• JavaScript, Lunr copies, carousel code, and SCSS used only by those removed implementations;
• consumer PostCSS and Autoprefixer steps that no remaining site asset needs.

Delete by reference, not with a blanket removal of layouts/. Home pages, download pages, and portals may still call local partials such as icons, search dialogs, blog rows, or tag filters.

Keep site-specific behavior

Keep content and code whose semantics belong to the product:

• product matrices and compatibility data;
• pricing, downloads, portals, solutions, and catalog pages;
• site-specific home-page composition;
• custom redirects, headers, analytics, or identity integrations;
• content components that encode business data rather than reusable presentation.

For the Pigsty family, pgvers, pgext_matrix, pgext_os_matrix, home-docs, and the current metric implementation remain at the site layer.

Reference-site matrix

The current migration plan uses these boundaries:

The matrix is a starting inventory, not permission to delete every similarly named file. Resolve actual template references in the target checkout.

Rehearsal workflow

Rehearse each migration in a disposable copy of the consuming site. Apply the local Oink workspace, remove one planned override group, block unintended network and frontend-tool access, and run the production build:

HUGO_MODULE_WORKSPACE=go.work hugo --gc --minify

Do not modify the source workspace during a rehearsal. Retain failed copies for diagnosis and record the exact theme commit, Hugo version, removed files, and output counts.

Current evidence

The latest recorded rehearsal on 2026-08-08 used Hugo Extended 0.164.0:

These are temporary-copy build results, not proof that the four production sites have been migrated or deployed.

Production rollout

For each site:

1. create a dedicated migration branch;
2. pin the OINK candidate and record its source commit;
3. remove one coherent override group at a time;
4. run a clean Hugo-only build and focused automated tests;
5. compare representative home, docs, blog, special, and 404 pages;
6. check mobile navigation, both color modes, language switching, search, print, and the site’s retained business components;
7. deploy a preview and verify its real URLs and requests;
8. merge and deploy only after review, then perform production smoke tests.

Record deliberate differences instead of forcing pixel equality where OINK intentionally changes the shell.

Rollback

Keep the pre-migration theme pin, site commit, and known-good deployment artifact. A rollback should restore all three consistently. Reintroducing a random subset of copied layouts against the new theme creates a hybrid state that is harder to diagnose than either complete version.