OINK migration boundary

This is source and configuration guidance, not a release ledger. Local source, commit, tag, push, consumer pin, deployment, and production parity remain separate states. For the reader-facing upgrade procedure, see Upgrade.

Toolkit scope

bin/migrations/oink06.py only scans and automatically rewrites Markdown files under a site’s content directory, including supported YAML front matter. It does not rewrite Hugo configuration, data files, layouts, assets, modules, or generated output. TOML/JSON front matter and ambiguous Markdown are reported with positions for manual review.

Dry-run is the default and a completed migration is idempotent:

python3 bin/migrations/oink06.py report --sites <dir>... --md report.md --json report.json
python3 bin/migrations/oink06.py migrate --site <dir>
python3 bin/migrations/oink06.py migrate --site <dir> --write
python3 bin/migrations/oink06.py check --site <dir>

Code-fence contents are not rewritten, including fences that begin on the same line as an ordered or unordered list marker, with optional blockquotes. An extra literal quote prefix inside a code example does not close that fence. book_figures.py retains narrow TPME, DDIA v1/v2, and pg-internal profiles; it is not a generic parser.

The isolated validation tools bin/measure-baseline.py and bin/sites/build-all.py reject snapshot destinations that overlap any input site, the running tools checkout, the selected theme checkout, or another snapshot before deleting existing output. This includes --keep destinations reached through symlink aliases and an alternate --theme checkout.

Updating consumer repositories

After publishing a theme release, inventory maintained consumer checkouts and upgrade their exact pins. The theme’s bin/update-consumers.py scans immediate project directories under the supplied roots; 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.

python3 bin/update-consumers.py v1.2.0 --roots ~/www ~/pgsty
python3 bin/update-consumers.py v1.2.0 --roots ~/www ~/pgsty --write --check

The first command only reports adoption. The second updates go.mod and OINK’s go.sum entries, verifies the exact module graph, and builds each selected site with warnings fatal. It disables GOWORK, Hugo’s module workspace, and environment module replacements. Logs and original module files go to a temporary report directory, or an explicit --report-dir. The tool restores module files if the update fails; a build failure leaves the new pin available for diagnosis and returns a failing status. An unreadable scan root or malformed consumer module is recorded as a failed entry; the inventory continues through the remaining sites and exits nonzero. An explicitly selected missing or non-consumer directory also fails visibly.

Linked worktrees, hidden copies, and non-default branches are skipped. Review all skipped and blocked entries: --sites <path>... explicitly selects a reviewed checkout, including one with existing module edits. OINK replacements in go.mod require manual resolution. Vendored themes require a separate review before --refresh-vendor, which backs up and regenerates _vendor/; changing a module pin alone does not update a vendored theme.

Preserve unrelated work, update current theme-version references in site READMEs and configuration, and run each site’s owning checks and visual review. The tool does not edit content, commit, push, or deploy. Record those completion states separately, including consumers already on the target tag.

0.4 content to current forms

Configuration and front matter

The following configuration changes are manual; the toolkit may report matching front-matter keys but never edits site configuration.

Prism, rss_sections, and algolia_docsearch are removed. Chroma is the only highlighter; Algolia configuration is search.algolia. Page overrides drop the ui. prefix. 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_attribution with upstream_link plus upstream_name, upstream_copyright, upstream_license, and upstream_notice; rename downstream_modified to upstream_modified.
• Replace the release map with one GitHub release_url; remove release_products and release_group_by_product from release indexes.
• Blog and default dates now default to ISO 2006-01-02; retain explicit time_format_blog or time_format_default for prose dates.

Removed names warn and take the documented safe fallback or render nothing; ordinary previews continue, while --panicOnWarning rejects them at a strict gate. blog_index_toggle, featured_image: hero, toc_style, and toc_taxonomies are additive opt-ins. They introduce no content type; immersive reading stays on the ordinary blog shell.

Prerequisites and validation

Enable Goldmark unsafe rendering, block attributes, and standalone block images as shown in the component contract. Enable passthrough explicitly for \(...\), \[...\], or $$...$$; Hugo does not merge theme markup config.

Run the smallest source and output checks for the changed contract with the pinned Hugo Extended 0.165.0 toolchain, JS tests when runtime changes, and strict root and subpath builds. For maintained sites, inspect representative EN/ZH Docs and Blog routes at desktop and narrow widths, then record pin, deployment, and hosted parity separately.