Upgrade
To upgrade OINK, change the pinned module version. Then confirm that the site builds with reviewed diagnostics. Most content needs no changes. To convert 0.4 shortcodes to current native Markdown forms, use the migration tool. It starts with a dry run and avoids manual edits to hundreds of files.
An upgrade changes rendered output. Before you start, create an upgrade branch. You can discard that branch if you cancel the upgrade.
Maintained sites use Hugo Extended 0.168.0 and its built-in LibSass. No
external Sass installation is required. Do not enable --panicOnWarning or
HUGO_PANICONWARNING; Hugo’s built-in LibSass deprecation warning is
expected. Update Hugo workflow pins when upgrading; older-Hugo requirements
in the sections below describe those historical releases only.
Upgrade to 1.5.1
OINK v1.5.1 stabilizes the opt-in Duo View
introduced in 1.5.0 and corrects RSS, Print, navigation, validation, search, and
accessibility behavior. Sites that leave params.ui.compare unset build the exact
same pages and outputs as before. See the 1.5.1 release notes.
Verify public module resolution with replacements and workspaces disabled, pin
github.com/pgsty/[email protected], and build with --printPathWarnings. If you
enable params.ui.compare: true:
- Keep explicit
{#id}heading anchors aligned across translations so Sync Scroll can match sections accurately. - Set
languages.<lang>.params.ui.compare: falsefor any language that should neither display the reader nor appear as a target language. - Guard custom analytics snippets in
head-end.htmlwithwindow.OinkComparePaneso pane loads are not counted twice. Note that a local override of Hugo’sgoogle_analytics.htmlpartial is not used whencompareis enabled; see Analytics and SEO. - Allow same-origin frames (
frame-src 'self') in your Content Security Policy and make sure your server does not block same-origin framing withX-Frame-Options: DENYorframe-ancestors 'none'. - Open a translated Docs, Book, or blog page and verify that Open bilingual view loads the target language, syncs scrolling across shared headings, and switches cleanly on narrow screens.
Upgrade to 1.4.0
OINK v1.4.0 keeps the Hugo-only build boundary and adds local PlantUML,
unified diagram reading, richer local search, the opt-in table reader, and the
gallery blog layout. See the 1.4.0 release notes.
Verify public module resolution with replacements and workspaces disabled.
Pin github.com/pgsty/[email protected], build with --printPathWarnings, and review
navigation, image viewing, and reader settings. Source-copy consumers must also
refresh their fixed theme files; changing go.mod does not update a vendored copy.
OINK v1.3.1 repairs Markmap text contrast and fixed-TOC footer clearance, and
adds opt-in layouts for technical tables and long FileTree comments. Existing
content keeps its default appearance. Enable technical table layout
or FileTree wrap=true only where complete technical text is needed.
Keep preset: paper and the explicit [paper, slate, ink, terminal] menu when
the site offers all four styles. The 1.3.1 notes describe
these fixes and credit their contributor.
Read the release notes first
Keep params.plantuml: true or
plantuml.enable: true and remove svg_image_url to use the two bundled
browser scripts. No additional software or rendering service is required.
Keep a nonempty endpoint to retain server mode. To disable rendering entirely,
set params.plantuml: false or plantuml.enable: false; an empty endpoint now
selects local mode. Review
unsupported includes, libraries, and CSP requirements
before switching an existing diagram collection.
Each version’s release notes describe its changes, breaking changes, and upgrade steps. Before upgrading, read the target version’s notes:
- The release series in this site’s project blog
- The Releases page on GitHub
The notes identify required content changes, removed configuration keys, and changed default behavior. Read them to understand differences in the upgraded pages.
Upgrading the Hugo Module
For a production site, pin a published release tag or an explicitly selected
immutable commit. Do not follow a branch or use @latest. The example below
upgrades to the published v1.5.1 tag. Before you select a later tag, verify
that the release is published and its module resolves:
When selecting a tag, confirm that the module graph shows that exact version.
An explicitly selected immutable commit normally uses a Go pseudo-version
in go.mod. Commit the resulting go.mod and go.sum.
For the published tag in this example, go.mod contains:
make dev and make check set HUGO_MODULE_REPLACEMENTS for that command
only, using the sibling theme checkout. To verify a release tag, remove
environment replacements, disable GOWORK and HUGO_MODULE_WORKSPACE, and
check for persistent replace directives or _vendor/. See the
preview guide.
For a Git submodule, first confirm that it has no local edits. Fetch the tags. Check out the exact published version. Do not follow its remote branch:
Commit the updated submodule pointer after validation. For an offline archive
or clone, replace themes/oink/ with the selected version’s complete tree and
confirm that theme: still matches the directory name. The install-method
tradeoffs are in
From scratch and other install methods.
What to do after upgrading
These commands clear potentially stale caches, rebuild with the new version, and review the visible diagnostics.
--logLevel info includes informational diagnostics, while
Warnings remain visible. Review the deprecation messages
emitted by the pinned Hugo version before upgrading it; the severity and
removal schedule depend on the deprecated feature.
After the build passes, visually check the home page, a documentation page, a blog page, and the 404. Check both languages, both color schemes, the print view, and every site customization.
Upgrading from 1.0 to 1.1
No source migration was required from 1.0.0 to 1.1.0. Its Go 1.27.0 module directive was unchanged from 1.0.0. Validate current upgrades with Hugo Extended 0.168.0. Historical toolchain details remain in the 1.1 release note.
Review the affected surfaces before choosing the new pin:
Languages- All 32 interface catalogs have the same native-message schema. Check the site’s language labels, plural counts, and RTL direction. The site remains responsible for authored translations.
Taxonomies- Root pages become term-card directories with a taxonomy switcher. Review any taxonomy-template or CSS overrides, author portraits, and localized breadcrumbs.
Sidebars- Cached trees preserve effective page settings and remain usable without JavaScript. Test collapse, hover restore, mobile drawer, and keyboard focus. Hidden content must leave the focus order.
Groupssidebar_divider: trueretains a section’s children. Addbuild.render: neveronly if you intentionally omit the group’s own outputs. Verify child navigation, breadcrumbs, paging, Print, and Book contents.Custom scripts- Feature-detect
OinkSidebarandOinkCommandPalette.registerSearchTailif an integration must also support 1.0.0. Restore branch state through the API rather than changing classes or ARIA attributes directly.
params.ui.image_zoom and params.offline_search remain off by default. The
new search hook does not enable a remote provider or add query telemetry.
params.ui.scroll_spy and page-level scroll_spy remain accepted no-ops in
1.x; removing the obsolete patch does not disable normal outline tracking.
Compare affected site-level copies of theme code with the new implementation. Then update or remove those copies. Otherwise, an old image-zoom script or sidebar partial continues to override the upstream fix.
To test local theme changes with the documentation site, use its sibling theme checkout without committing a filesystem replacement:
These commands validate the local checkout. For release acceptance, pin the published version, build without a module replacement, then validate the deployed pages. The authoring and API details live in content groups, the sidebar contract, search actions, and image zoom.
Upgrading from 1.1 to 1.2
Paper is the default in OINK 1.2.0. Set params.ui.preset: slate before
adopting this change if the site must retain its existing appearance.
preset_menu: true enables reader choice; its default remains false.
Ink and Terminal require an explicit preset or menu list. Their buttons do
not carry experiment badges; the configuration opt-in remains unchanged.
Review custom dark brand selectors as described in Brand.
OINK 1.2.0 is available as a published tag. Apart from the default appearance change above, no content migration is required. Validate current upgrades with Hugo Extended 0.168.0, then verify the site:
- Check the chosen preset, light/dark icons, keyboard and mobile menus, saved preferences, and custom font/accent overrides. Sun means light; moon means dark. Switching styles must not change the saved light/dark preference.
- Recheck explicit navigation, hidden subtrees, page links, Blog pagination canonicals, and SEO alternates for pages without translations.
- Check CJK keyword-only search summaries and outline links with literal percent signs. Compare source-derived Edit, History, and Create child links on Windows or mounted content; mappings must yield repository-relative paths.
- Check Landing content with JavaScript disabled or blocked, preserved metric formatting, dialogs and keyboard shortcuts, copy fallback, Draw.io controls, and numbered equations at narrow widths.
- Run a production build for diagram endpoints and resource alt metadata;
malformed values now produce a warning and use a safe fallback. To disable
rendering intentionally, use
params.plantuml: falseorparams.drawio.enable: false. - Use the revised PDF and migration tools when testing publication or content conversion. Review PDF remote-resource opt-ins and migration diffs, including code examples nested in lists. The consumer-upgrade helper ships with 1.2.0 for inventory, module updates and exact-version validation.
The Architecture, Components, Shell, and Migration contracts describe the published 1.2.0 behavior.
The content migration toolkit
Several 0.4 shortcodes now use native Markdown forms. The theme repository ships a conversion tool that requires only the Python standard library:
Follow these four rules when you use the tool:
- A dry run is the default. Only
--writechanges files. Run the dry run, read the diff, and then write. - A second run should change nothing. If a second
--writereports changes, a transformation has not converged. Stop and inspect those files. - The tool leaves text inside fences unchanged. Documentation examples of old syntax therefore remain intact.
- If the tool cannot express a construct, it leaves that construct unchanged. It reports
file:lineand a reason for manual work. This is not a failure.
To convert one class first, use --only with the keys in the table’s last
column:
After conversion, rebuild, review warnings, and inspect the rendered pages. The tool guarantees correct syntax. You must verify the intended meaning.
The 0.4 → current syntax map
Each page under Components describes the new form and its parameters.
Migrating from Docsy
OINK is a hard fork of Docsy. It retains the content model, td- naming, Sass
variables, and most front matter. Migration mainly requires removing site
copies of the shared shell. The theme’s implementation then supplies the shell.
You do not need to rewrite the prose.
-
Pin the target version. Change
go.modto an OINK release tag, or use a complete versioned archive. During evaluation, an uncommittedgo.workcan point at a local checkout. -
Inventory the overrides. Classify each site-level file under
layouts/,assets/, andstatic/into four groups. Delete verified copies of the shared shell. Delete or mechanically rename components that OINK already provides. Retain brand customization in the smallest suitable hook. Keep business-specific data and interaction in the site. Delete files in reference order. Do not emptylayouts/at once. The home page or download page may still call a partial that you plan to remove. -
Move the configuration. Keep
title,languages.*,github_repo,github_branch,page_width, andparams.ui.*in their existing semantic positions. OINK adds no separate namespace. Enable search and the logo with these keys:hugo.ymlDocsy’s camelCase search keys have been renamed in OINK:
offlineSearch,offlineSearchIndex,offlineSearchMaxResults,offlineSearchOnServeandofflineSearchSummaryLengthall become their underscored forms. Rename them deliberately. The old migration registry stopped the build and named the replacement. That registry was removed. The theme now ignores an old key, so search remains off without a message. -
Fonts and styling compatibility. The Docsy Sass variables in
assets/scss/_variables_project.scssstill supply seed values for font roles. You do not need to delete them for an upgrade. Each of$td-fonts-serif,$font-family-sans-serif,$headings-font-family, and$font-family-codesupplies its role. The theme no longer reads Docsy’s Google Fonts switches$td-enable-google-fonts,$td-google-font-name, and$td-web-font-path. These unused switches cause no failure and have no effect. OINK bundles Inter, Chakra Petch, and IBM Plex Mono. Neither preset requests Google Fonts. To change fonts, use the token layer. See Brand and appearance. -
Convert the shortcodes. Docsy’s
alert,pageinfo,tabpaneandcardfamilies all have a current counterpart; convert them in bulk with the migration toolkit above, one--onlyclass at a time. -
Delete one group at a time. Build after each group. First test on a scratch copy. Record the theme commit, Hugo version, removed files, and generated HTML file count. After you confirm equivalent behavior, repeat the process on the production branch.
The “delete after verifying” class in step two is usually these files:
layouts/baseof.htmland the shared docs / blogbaseof*.html;- The navbar, footer, sidebar, TOC, search and head CSS partials and their hooks;
- The old brand documentation shell partials;
- Copies of the
asciinema,echarts,infographic,doc-carousel,details,tab/tabpane, card andparamshortcodes; - The JavaScript, Lunr copy, carousel code and SCSS that served only those implementations;
- PostCSS and Autoprefixer steps no site asset needs any more.
Two types of problem can appear after deletion.
A site script can report $ is not defined. OINK does not bundle jQuery,
which Docsy loaded in each page’s <head>. The theme does not need jQuery.
If your site needs it, load it in the site:
A home page that uses Docsy’s blocks/* fails an OINK build with
template for shortcode "blocks/cover" not found. OINK has no such shortcode
family. Use home page sections in data/home/<language>.yaml, or set
layout: landing on the page. See
Home and landing pages.
Upgrading from 0.4
0.4 changed several defaults. If an upgrade adds or removes a page feature, check these settings first:
-
Sequential paging is on by default.
docs,book, andblogpages have previous / next links at the page end. Documentation follows the sidebar tree. Blog pages follow time. For a page intentionally outside a sequence, setpager: false. -
The navbar appears on every layout. Its compact state has one row of icon navigation and no second mobile accordion menu. Remove local scripts and tests that depend on the old mobile menu. To disable the navbar for a section, set
navbar_enabled: falsein a cascade. -
The footer defaults to
fatfor the site. It accepts onlyfat/slim/none. Store footer data indata/footer/<language>.yaml, ordata/footer.yamlfor a single-language site. A remainingfooterkey indata/homeproduces a warning with the new location. -
Single-key navigation is on by default.
/opens full search, and\opens command-only mode. Update training material that describes the old behavior. Page actions now use a split button beside the breadcrumbs. -
The code block DOM changed. A
.td-codewrapper now encloses the original.highlight. Both.highlightand.chromaremain. In site CSS, replace a direct child selector such as.td-content > .highlightwith the descendant selector.td-content .highlight. -
Two ICP footer parameters were removed. The keys
footer_icpandfooter_icp_urlbecame one string that accepts inline Markdown.hugo.yml -
For mathematics, enable passthrough in the site. Hugo does not merge a theme’s
markupconfiguration. If the site uses\(…\),\[…\], or$$…$$, enable Goldmark passthrough in its ownhugo.yml. See Math.
The complete configuration for all of these is in Configuration and Layouts and page types.
Verify
After “the build passed”, the upgrade still requires checks. Inspect each surface:
This site’s full gate is:
Another site runs the equivalent build, link, output and browser checks; the details are in Troubleshooting.
Complete the final checks in the real environment. Deploy a preview. Verify its pages and browser network requests at the real URL. After review, merge the upgrade and run a production smoke test.
Rollback
To roll back the theme, restore the version pin:
Three principles:
- Keep the pre-upgrade module pin, the site commit and the known-good deployment artifact, and restore all three together.
- Do not perform a partial rollback. Old layout copies over a new theme produce a mixed implementation. This is harder to diagnose than either complete version.
- Keep the upgrade branch and its acceptance evidence. A rollback first restores production. It does not discard completed upgrade work.
Rolling back the deployed output itself (republishing the previous deployment) is in Deploy.
Related
- Deploy — rolling back deployed output
- Troubleshooting — reading a build error after an upgrade
- Local preview — clearing caches and the
go.workworkspace - From scratch and other install methods — weighing the four install methods
- Components — each component’s current form