# Update OINK

> Update the theme, Hugo Extended, and local overrides safely.

---

LLMS index: [llms.txt](/llms.txt)

---

These pages describe the OINK update contract. A **target release** is the
version that you are moving the site to. Read its release post before starting:
it records breaking changes, required actions, and the validated Hugo range.

<a id="update-node"></a>

OINK consumer builds do not install Node.js packages. npm remains repository
tooling for theme maintainers, not a site-update step.

## Before you update

- Work from a Git branch or another recoverable copy of the site.
- Record the currently pinned theme revision and Hugo Extended version.
- Build the current production site once so that new failures can be separated
  from pre-existing ones.
- Read every release post between the current and target versions; do not skip
  intermediate migration actions.

## Order of steps {#update-order}

Perform the update in this order:

1. [Update Hugo](#update-hugo) if the target release changes its supported
   range.
2. [Update the theme](#update-theme) using the site's installation mode.
3. [Review theme overrides](#update-overrides).
4. [Check the site](#check) in development and production builds.

## Update Hugo {#update-hugo}

Install a Hugo Extended version supported by the target release. Update the same
version in local developer setup, CI, Cloudflare Pages, Netlify, container
images, and any cache keys. Verify the selected binary before building:

```sh
hugo version
```

The current validation baseline is Hugo Extended `0.164.0`; the theme's current
minimum is `0.160.1`. A release post takes precedence if it changes either
value.

## Update the theme {#update-theme}

Use the page matching the site's installation mode:

- [Hugo module](hugo-module/)
- [Git submodule or clone](git/)
- [Migration from the upstream npm package](npm-package/)

For a released archive, replace the existing theme directory with the target
archive only after preserving site-owned overrides. Verify its checksum and keep
`LICENSE`, `NOTICE`, and `VENDOR.json` with the distribution.

## Review theme overrides {#update-overrides}

If the site overrides theme files, compare each override with its new theme
counterpart and port relevant changes. Check these directories:

- `assets/`
- `i18n/`
- `layouts/`
- `static/`

Remove an override when the theme now provides the same behavior. Keep site
business components, product pages, and brand assets at the site layer.

## Check your site {#check}

Run both a development preview and the exact production command. For the
Hugo-only contract, the production build is:

```sh
hugo --gc --minify
```

Verify at least the following:

- [ ] The build completes without errors, warnings, or deprecation notices.
- [ ] English and Chinese home, documentation, and blog pages render.
- [ ] Navigation, breadcrumbs, table of contents, stable heading links, and
      language switching resolve correctly.
- [ ] Local search returns results in both languages.
- [ ] Dark and light modes, mobile navigation, and print output remain usable.
- [ ] Pages load only the local runtimes they use; default pages make no
      theme-owned third-party subresource requests.
- [ ] Mermaid, KaTeX, Markmap, Swagger UI, Redoc, and any used content
      components still render.
- [ ] Site-owned shortcodes and business pages remain intact.

Finally, run every release-specific check from the target release post.

---

Section pages:

- [Update the OINK Hugo module](/docs/update/hugo-module/): Update a site that imports the theme as a pinned Hugo module.
- [Migrate from the Docsy npm package](/docs/update/npm-package/): Remove the upstream npm theme package from an OINK consumer site.
- [Update an OINK Git submodule or clone](/docs/update/git/): Update an OINK theme stored as a Git submodule or clone.
- [Migrate a Docsy site to OINK](/docs/update/convert-site-to-module/): Replace a Docsy consumer toolchain with the Hugo-only OINK theme.