OINK migration boundary
This contract describes OINK v1.5.1.
This page defines the maintainer migration toolkit and configuration boundaries. See Upgrade for the reader-facing upgrade guide.
Toolkit scope
bin/migrations/oink06.py scans and automatically rewrites only Markdown in a site’s content directory, including supported YAML front matter.
It does not rewrite Hugo configuration, data, layouts, assets, modules, or generated output.
It reports TOML/JSON front matter and ambiguous Markdown with source positions for manual review.
Dry-run is the default. Completed migrations are idempotent:
Code-fence contents are not rewritten, including fences starting on the same line as ordered or unordered list markers, with optional blockquotes.
An extra literal quote prefix within a code example does not close the fence.
book_figures.py keeps narrow TPME, DDIA v1/v2, and pg-internal profiles. It is not a generic parser.
Before deleting existing output, bin/measure-baseline.py and bin/sites/build-all.py reject snapshot destinations that overlap protected locations.
These locations include input sites, the running tools checkout, the selected theme checkout, and other snapshots.
The check includes --keep destinations through symlink aliases and alternate --theme checkouts.
Updating consumer repositories
After publishing a theme release, inventory maintained consumer checkouts and update their exact pins.
bin/update-consumers.py scans primary project directories under supplied roots and their site/ directories.
It does not recurse into archives, generated sites, caches, or theme fixtures.
The tool ships with OINK 1.2.0. Run it from the theme checkout to inventory consumers and upgrade them to the published tag.
The first command only reports adoption.
The second updates go.mod and OINK’s go.sum entries, verifies the exact module graph, and builds selected sites with fatal warnings.
It disables GOWORK, Hugo’s module workspace, and environment module replacements.
Logs and original module files go to a temporary report directory or the explicit --report-dir.
Failed updates restore module files. Failed builds keep the new pin for diagnosis and return failure.
Unreadable roots or malformed consumer modules become failed entries. Inventory continues through other sites and exits nonzero.
Explicitly selected missing or non-consumer directories also fail visibly.
Linked worktrees, hidden copies, and non-default branches are skipped. Review every skipped or blocked entry.
An explicit project root resolves to its site/ directory when that directory contains the Hugo site and the root is not itself a Hugo configuration or OINK consumer. An unrelated Go application’s root go.mod does not prevent this resolution. An actual root consumer takes precedence.
--sites <path>... selects a reviewed site explicitly, including checkouts with existing module edits and source directories without Git. Source-only directories are skipped during automatic discovery until selected explicitly; they receive the same file backups and build checks.
Classic themes/oink consumers are listed for separate maintenance: update a clean Git submodule to the published tag, or back up and replace a verified upstream source copy. Preserve offline builds and site-level overrides, then run the owning site checks. The module updater does not rewrite classic theme directories.
Manually resolve OINK replacements in go.mod.
Review vendored themes separately before --refresh-vendor, which backs up and regenerates _vendor/.
Changing a module pin alone does not update vendored themes. Hugo’s resolved module graph determines whether OINK actually uses vendor output. A retained snapshot bypassed by ignoreVendorPaths is preserved and does not block a published-module upgrade.
To offer all four styles with Paper as the site default, set the site configuration explicitly:
preset_menu: true offers the stable styles and the site default; the explicit list also opts into Ink and Terminal. These settings persist across later pin upgrades. Review sites with a custom shell separately: configuration alone does not add appearance controls to templates that bypass OINK’s shell.
The maintainer checkout also supports --check-appearance together with --check. It checks the fresh rendered home pages, including localized entries, for Paper as the default and all four style controls. Sites that disable Home are checked at their documentation entries; redirect aliases are omitted. Browser interaction and each site’s owning checks remain separate.
Preserve unrelated work. Update current theme-version references in site READMEs and configuration. Run each site’s owning checks and visual review. The tool updates module pins and runs build checks without editing content or committing.
0.4 content to current forms
| Removed form | Current form | Toolkit key |
|---|---|---|
alert, details, pageinfo, raw disclosure |
> [!TYPE] callout |
callout |
tabpane, legacy tab, code-group, code-tab |
adjacent {tab=} blocks or tabs / tab |
tabs |
FileTree shortcodes or {.filetree} list |
filetree fence |
filetree |
Gallery shortcodes or {.gallery} list |
gallery fence |
gallery |
| ECharts / infographic shortcode | same-named data fence | datafence |
| Docsy card families | .cards list or cards / card |
cards |
imgproc, image |
Markdown image + attributes | image |
readfile |
include |
include |
fence filename= |
title= |
fencetitle |
badge outline= |
remove outline |
badge |
leaf example, book-figures kind= |
eg, explicit book-* index |
eg |
| percent-delimited fields | angle-delimited fields / field |
fieldsdelim |
Docsy _param placeholders and card header= highlights |
Font Awesome / badge / param or callout |
param_placeholders |
| unsupported legacy shortcodes | manual review with source position | reportonly |
Configuration and front matter
Make these configuration changes manually. The toolkit may report matching front matter keys but never edits site configuration.
| Old | Current |
|---|---|
offlineSearch* |
offline_search* |
disable_click2copy_chroma |
ui.code_copy (inverted) |
content_width |
`reading_width: slim |
github_url |
github_repo |
ui.no_left_sidebar |
ui.sidebar_enabled (inverted) |
| breadcrumb aliases | ui.breadcrumb |
ui.scrollSpy |
No behavioral replacement; ui.scroll_spy remains a quiet 1.x compatibility no-op |
ui.showLightDarkModeMenu |
ui.dark_mode.show_menu |
ui.readingtime |
ui.reading_time |
ui.ul_show |
ui.sidebar_expand_levels |
ui.docs_root |
ui.docs_sidebar_root |
ui.pager |
ui.pager_types |
{ enable: bool } annotation/zoom/keyboard/reading maps |
bare booleans |
ui.typography.preset |
ui.typography |
print.disable_toc |
print.toc (inverted) |
Prism, rss_sections, and algolia_docsearch are removed.
Chroma is the only highlighter. Algolia configuration uses search.algolia.
Page overrides omit ui..
Legacy hide_feedback, hide_readingtime, exclude_search, content_width, camelCase manual links, and nested front matter ui maps are reported with replacements.
0.5 to 0.6
- Replace
upstream_attributionwithupstream_linkplusupstream_name,upstream_copyright,upstream_license, andupstream_notice; renamedownstream_modifiedtoupstream_modified. - Replace the
releasemap with one GitHubrelease_url; removerelease_productsandrelease_group_by_productfrom release indexes. - Blog and default dates now default to ISO
2006-01-02; retain explicittime_format_blogortime_format_defaultfor prose dates.
Removed names warn and use the documented safe fallback or render nothing, allowing ordinary previews to continue.
blog_index_toggle, featured_image: hero, toc_style, and toc_taxonomies are additional opt-ins.
They add no content type. Immersive reading remains on the ordinary blog shell.
Prerequisites and validation
Enable Goldmark unsafe rendering, block attributes, and standalone block images as specified in the component contract.
Enable passthrough explicitly for \(...\), \[...\], or $$...$$. Hugo does not merge theme markup configuration.
Run the smallest source and output checks for the changed contract with pinned Hugo Extended 0.168.0. For runtime changes, also run JS tests. Run production root and subpath builds. For maintained sites, inspect representative EN/ZH Docs and Blog routes at desktop and narrow widths.