Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Operations

Preview, deploy, and maintain a site. Configure comments, analytics, and SEO. Upgrade the theme and diagnose problems.

Use this section after you write the content. Preview the site locally, build and deploy the output, configure comments and analytics, track theme versions, and diagnose problems. The previous five sections describe the site’s appearance and content. This section describes its build, deployment, and diagnosis.

Find it by task

What you want to do Where to go
See a change on your own machine Local preview
Build a deployable public/ Local preview
Deploy to GitHub Pages / Cloudflare / Netlify Deploy
Deploy to a subpath such as example.com/docs/ Deploy
Let readers comment at the end of a page Comments
Connect Google Analytics or a self-hosted alternative Analytics and SEO
Configure correct search engine indexing Analytics and SEO
Upgrade the theme, or migrate from Docsy or 0.4 Upgrade
Diagnose a build error, missing search results, or a 404 Troubleshooting

1 - Local preview

Preview changes with hugo server and build deployable output with hugo. Neither Node nor a CDN is required.

Use hugo server to preview local changes. Use hugo to produce a public/ directory that you can deploy to any static host. Install Hugo Extended (0.168.0 or newer) on the machine. If you install the theme as a Hugo Module, also install Go. The build does not require Node.js, npm, or PostCSS. Only this repository’s regression checks use those tools.

The preview server

From the site root (the directory holding hugo.yml):

Terminal
hugo server

Open http://localhost:1313/. When you save a file, Hugo rebuilds the site and refreshes the browser. Switching Git branches also triggers a rebuild. The first start is slower. For a Hugo Module, Hugo downloads the module through Go into its cache. Later starts read the cache.

The switches worth knowing

-D / --buildDrafts , defaultoff
Also builds pages with draft: true
-F / --buildFuture , defaultoff
Also builds pages whose date / publishDate is in the future
-E / --buildExpired , defaultoff
Also builds pages whose expiryDate has passed
--disableFastRender , defaultoff
Re-renders the complete site on every change instead of using incremental rendering
-M / --renderToMemory , defaultoff (writes to disk)
Renders only in memory. Writes no public/
-N / --navigateToChanged , defaultoff
The browser opens the page you saved
--bind , default127.0.0.1
The listen address. Use 0.0.0.0 for access from a LAN or outside a container
-p / --port , default1313
The listen port
--minify , defaultoff
Minifies the preview too, to reproduce production rendering
--printPathWarnings , defaultoff
Warns when two pages write to the same target path

The combination used while developing this site:

Terminal
hugo server -DFE \
  --disableFastRender --renderToMemory --minify \
  --printPathWarnings --logLevel info

-DFE means -D -F -E. It builds drafts, future pages, and expired pages together. Newly created pages are therefore visible while you write them.

A change that did not take effect

Hugo enables fast render by default. It rebuilds only the output that it identifies as affected. Changes to layouts, configuration, data/, or a file used by include can escape detection. If the page appears unchanged, follow these three steps:

  1. Restart with --disableFastRender. Check whether the change appears.
  2. Force a browser refresh (Cmd/Ctrl + Shift + R) to exclude browser cache as the cause.
  3. If the change still does not appear, clear the caches and restart.

Reaching it from another device

hugo server listens on 127.0.0.1 only, so no other device can reach it. To preview on a phone or another machine:

Terminal
hugo server --bind 0.0.0.0 --port 1313 --baseURL http://192.168.1.10:1313/

Set --baseURL to an address that the other device can reach. Otherwise, the page opens, but resources with absolute paths point to localhost. These resources include CSS and the search index.

Production build

Build deployable output with hugo, not hugo server:

Terminal
hugo --gc --minify --printPathWarnings

Hugo writes the output to public/. You can deploy it independently of the source tree. The four switches have these functions:

--gc
Clears cached resources in resources/_gen that are no longer referenced
--minify
Minifies the HTML, CSS, JS and XML output
--printPathWarnings
Warns when two pages use the same output path. This is the most common silent error on multilingual sites

Use Hugo Extended 0.168.0 and leave warnings visible. Do not enable --panicOnWarning or HUGO_PANICONWARNING: Hugo’s upstream LibSass deprecation warning is accepted. Invalid giscus settings or unsupported theme values also warn and fall back; review these diagnostics and the rendered output before publication.

This site’s CI uses the production command above, with local module replacements and workspaces disabled for published-pin acceptance.

baseURL and the build environment

baseURL lives in hugo.yml and can be overridden on the command line:

hugo.yml
baseURL: https://oink.pgsty.com
Terminal
hugo --minify --baseURL "https://example.com/docs/"

When deploying to a subpath, --baseURL must include that path segment; the details are in Deploy.

Select the build environment with -e / --environment. The default is production for hugo and development for hugo server. This choice has three visible effects in OINK:

  • Only production emits <meta name="robots" content="index, follow">. Other environments emit noindex, nofollow.
  • In production, robots.txt contains Allow: /. In other environments, it contains Disallow: /.
  • Only production renders Hugo’s Google Analytics template, and only there are static assets fingerprinted with SRI.

For preview deployments, including PR previews and staging, use a non-production environment. The output automatically disables analytics and requests no indexing:

Terminal
hugo --minify --environment staging --baseURL "$PREVIEW_URL"

Previewing in a container

A container is optional. Use one if your team needs a pinned toolchain version or does not want to install Hugo on every developer’s machine.

Dockerfile
FROM debian:bookworm-slim

ARG HUGO_VERSION=0.168.0
ARG GO_VERSION=1.27.3
ARG TARGETARCH

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl git \
    && curl --fail --location -o /tmp/hugo.deb \
      "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-${TARGETARCH}.deb" \
    && apt-get install -y /tmp/hugo.deb \
    && curl --fail --location -o /tmp/go.tgz \
      "https://go.dev/dl/go${GO_VERSION}.linux-${TARGETARCH}.tar.gz" \
    && tar -C /usr/local -xzf /tmp/go.tgz \
    && rm -rf /var/lib/apt/lists/* /tmp/hugo.deb /tmp/go.tgz

RUN case "${TARGETARCH}" in \
      amd64) sass_arch=x64; sass_sha=a530ee08d5792c80bdb9d9614b45fb58219c890cb42a280a80775f0af9c29582 ;; \
      arm64) sass_arch=arm64; sass_sha=40c7a1946f654163daab34d3824cf572d2e72cc48a2efcf9ca0a33140007d374 ;; \
      *) exit 1 ;; \
    esac \
    && curl --fail --location -o /tmp/sass.tgz \
      "https://github.com/sass/dart-sass/releases/download/1.105.2/dart-sass-1.105.2-linux-${sass_arch}.tar.gz" \
    && echo "${sass_sha}  /tmp/sass.tgz" | sha256sum --check \
    && tar -C /opt -xzf /tmp/sass.tgz \
    && rm /tmp/sass.tgz

ENV PATH="/usr/local/go/bin:/opt/dart-sass:${PATH}"
WORKDIR /src
EXPOSE 1313
ENTRYPOINT ["hugo"]
CMD ["server", "--bind", "0.0.0.0", "--disableFastRender"]
Terminal
docker build -t oink-hugo .

# preview: mount the site source, and the Go module cache with it
docker run --rm -it -p 1313:1313 \
  -v "$PWD:/src" \
  -v "$HOME/go/pkg/mod:/root/go/pkg/mod" \
  oink-hugo

# production build: override the default server command
docker run --rm --user "$(id -u):$(id -g)" \
  -v "$PWD:/src" \
  oink-hugo --gc --minify

The image includes Go because Hugo needs it to resolve and download a Hugo Module. If the site uses a submodule, offline archive, or plain clone, you can remove Go. This makes the image much smaller.

Do not let root write public/

A container process runs as root by default. The generated public/ belongs to root, so the host cannot delete it. In a shared environment, map the user ID with --user "$(id -u):$(id -g)". The production build command above already does this.

The image requires no Node.js, npm, or PostCSS. It should not fetch remote browser assets. For a network-isolated environment, mirror the base image and the Hugo and Go packages in advance.

Clearing caches

Hugo stores intermediate output in three places. Clear the smallest scope first:

public/ , ContentsThe previous build’s output
A deleted page remains live. You can also let the build clear this directory with hugo --cleanDestinationDir
resources/_gen/ , ContentsProcessed images and compiled CSS
Image processing parameters, fonts, or the accent color changed, but the page still shows the old appearance
hugo mod clean , ContentsThe Hugo Module cache
The theme version changed, but the old version still resolves. Add --all to clear the complete module cache
Terminal
rm -rf public resources/_gen
hugo mod clean          # only the modules this project uses
hugo mod clean --all    # the whole module cache; the next build downloads again

Add both public/ and resources/ to .gitignore. Never commit generated output.

Working on the theme alongside

If you change the theme and site together, temporarily select a local checkout with HUGO_MODULE_REPLACEMENTS. Leave go.mod unchanged:

Terminal
HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> /absolute/path/to/oink' hugo server

This site’s Makefile wraps those commands and expects the theme checkout at the sibling ../oink:

Makefile targets
make dev     # development server with ../oink substituted
make check   # full regression suite (npm test) with ../oink substituted
make build   # build with the version in go.mod
make serve   # preview server with the production configuration
Local overrides can mask the published version

CI and production builds can still inherit replacements or workspaces. Do not commit a workspace containing developer-machine paths. To verify a published tag, unset HUGO_MODULE_REPLACEMENTS and set both GOWORK=off and HUGO_MODULE_WORKSPACE=off. Also inspect persistent replacements in go.mod and Hugo configuration, and any _vendor/ copy; confirm the exact version in hugo mod graph under the same environment before building.

Verifying an offline build

For acceptance in a network-isolated environment, check both the build and the browser. Follow these six steps:

  1. Start from a verified theme archive and an empty module cache (hugo mod clean --all).
  2. Block outbound HTTP, HTTPS and the Go module proxy.
  3. Run the production build hugo --gc --minify --printPathWarnings.
  4. Browse pages in both languages: a documentation page, a blog page, the home page, the 404.
  5. Exercise search, the light/dark toggle, diagrams and content components.
  6. Check subresource origins and confirm there is no unexpected remote host.

For the last step, use the output checker from a theme checkout matching your pinned release. It needs Python 3, not this documentation site’s test framework. Replace both absolute paths below and use the same base URL as the build:

Terminal
python3 /path/to/oink/bin/check-output-security.py \
  --public /path/to/my-site/public --base-url https://docs.internal.example.com/

The script scans every href / src / srcset / poster and form action in all four outputs. Each value must be a site-relative path or use http / https / mailto / tel. The script rejects inline on* handlers and javascript: URLs. An <iframe>, <script>, <link>, <img>, <video>, <audio>, <embed>, <object>, or <source> that points to another host is an error. If the site intentionally embeds third-party content, use --third-party to permit it. For a multi-domain language configuration, add first-party hosts with --allow-host.

A passing check validates that commit in that environment. Repeat it for every theme candidate and after every bundled-dependency update.

Verify

A clean production build should look like this:

Terminal
rm -rf public resources/_gen
hugo --gc --minify --printPathWarnings

The build passes when it reports Total in … with no ERROR. Then check the following items:

  • Confirm that the log has no npm, PostCSS, Autoprefixer, or browser-asset download step. Such a step indicates upstream Docsy configuration.
  • public/ has sitemap.xml and robots.txt, and robots.txt reads Allow: /.
  • If local search is enabled, confirm that each language has an index in public/. Production filenames are offline-search-index.<language>.<hash>.json. Development filenames omit the hash. Open search and confirm that the actual data-td-index-src URL returns 200.
  • With hugo server, open one documentation page, one blog page, the home page, and the 404. Check both languages and both color schemes.

For a failing build or a wrong result, see Troubleshooting.

2 - Deploy

Publish public/ to GitHub Pages, Cloudflare Pages, or another static host. Set baseURL, review Content Security Policy, verify deployment, and prepare rollback.

An OINK site produces a plain static directory. You can deploy it to any host that serves static files. It requires no Node runtime, server-side rendering, or build plugin. On the host, run one command with the correct Hugo version. Publish public/ and set baseURL to match the final address.

First run a local production build with Hugo Extended 0.168.0 (using its built-in LibSass). Do not enable --panicOnWarning or HUGO_PANICONWARNING; keep warnings visible and review them (the upstream LibSass deprecation warning is expected).

Getting baseURL right

An incorrect baseURL is the most common source of failure. The page can open without an obvious error. However, the search index 404s, page action links use incorrect addresses, and some assets do not load.

For deployment at a domain root, use:

hugo.yml
baseURL: https://oink.pgsty.com

For deployment to a subpath (https://example.com/docs/), include that path in baseURL:

hugo.yml
baseURL: https://example.com/docs/

You can also override this value at build time. This lets you deploy one source to several locations:

Terminal
hugo --gc --minify --baseURL "https://example.com/docs/"
Do not fix a subpath with canonifyURLs

Keep Hugo’s default value false for canonifyURLs. OINK’s templates and content links resolve against baseURL. If the path is incorrect, correct baseURL. Enabling canonifyURLs rewrites relative links that were already correct. This makes the problem harder to diagnose.

If local search is enabled, open search. Inspect its index request in the browser’s Network panel. The request must use the correct language and deployment subpath, and return 200. Read the actual URL from the page’s data-td-index-src attribute. Production filenames are offline-search-index.<language>.<hash>.json. Development filenames have no hash. Do not guess the filename.

Choosing a host

If the source is on GitHub, one Actions workflow is sufficient. Actions builds the site and publishes the output through the Pages deployment API. You do not need a gh-pages branch. OINK Starter includes the file below. Copy it only if you assemble a site manually.

.github/workflows/github-pages.yaml
 1name: Deploy to GitHub Pages
 2
 3on:
 4  push:
 5    branches: [main]
 6  workflow_dispatch:
 7
 8permissions:
 9  contents: read
10  pages: write
11  id-token: write
12
13concurrency:
14  group: github-pages
15  cancel-in-progress: false
16
17env:
18  GO_VERSION: stable
19  HUGO_VERSION: "0.168.0"
20  # a workspace from a sibling checkout must never take part in a CI build
21  GOWORK: off
22  HUGO_MODULE_WORKSPACE: off
23  HUGO_CACHEDIR: ${{ github.workspace }}/.hugo_cache
24
25jobs:
26  build:
27    name: Build Pages artifact
28    runs-on: ubuntu-latest
29    steps:
30      - name: Check out source
31        uses: actions/checkout@v7
32        with:
33          fetch-depth: 0
34
35      - name: Set up Go
36        uses: actions/setup-go@v7
37        with:
38          go-version: ${{ env.GO_VERSION }}
39          check-latest: true
40          cache-dependency-path: go.sum
41
42      - name: Configure GitHub Pages
43        id: pages
44        uses: actions/configure-pages@v6
45
46      - name: Install Hugo Extended
47        uses: peaceiris/actions-hugo@v3
48        with:
49          hugo-version: ${{ env.HUGO_VERSION }}
50          extended: true
51
52      - name: Record build tool versions
53        run: |
54          go version
55          hugo version
56
57      - name: Download OINK
58        run: go mod download github.com/pgsty/oink
59
60      - name: Build
61        run: |
62          hugo --cleanDestinationDir --gc --minify --environment production \
63            --printPathWarnings \
64            --baseURL "${{ steps.pages.outputs.base_url }}/"
65
66      - name: Upload Pages artifact
67        uses: actions/upload-pages-artifact@v5
68        with:
69          path: public
70
71  deploy:
72    name: Deploy
73    environment:
74      name: github-pages
75      url: ${{ steps.deployment.outputs.page_url }}
76    runs-on: ubuntu-latest
77    needs: build
78    steps:
79      - name: Publish
80        id: deployment
81        uses: actions/deploy-pages@v5

OINK Starter ships this workflow. The following settings are required:

  • fetch-depth: 0 — if enableGitInfo is enabled, “last modified” and contributor information require the complete Git history. A shallow clone leaves them empty.
  • setup-go plus go mod download — Hugo needs Go to resolve the theme as a Hugo Module. For a submodule installation, use submodules: recursive instead. For an offline archive, commit themes/oink/. With either alternative, remove both Go steps.
  • GOWORK: off and HUGO_MODULE_WORKSPACE: off — exclude a local development go.work from the CI build. CI then verifies the published tag pinned in go.mod.
  • --baseURL "${{ steps.pages.outputs.base_url }}/" — a project site’s URL is https://<OWNER>.github.io/<REPO>/. Use the value computed by configure-pages instead of a hard-coded address. Warnings remain visible for review. Do not enable --panicOnWarning or HUGO_PANICONWARNING; the upstream LibSass deprecation warning is accepted.

In the repository, set Settings → Pages → Build and deployment → Source to GitHub Actions. Push to main. Check the first run on the Actions tab.

For a custom domain, enter it in the Custom domain field on the same settings page. Configure DNS as prompted. Then set baseURL in hugo.yaml to that domain. If the publishing process requires a CNAME file, put it at static/CNAME. Hugo copies it unchanged into public/.

OINK Starter ships .github/workflows/cloudflare-pages.yaml, a Direct Upload workflow. The production build stays in GitHub Actions and Wrangler uploads the same public/ artifact to a Cloudflare Pages project.

  1. Create a Direct Upload Pages project. Its name defaults to the repository name. To override it, set repository variable CLOUDFLARE_PROJECT_NAME.
  2. Add repository secrets CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN. The token needs Account → Cloudflare Pages → Edit.
  3. Run Deploy to Cloudflare Pages manually once. To deploy every push to main, set repository variable CLOUDFLARE_PAGES_ENABLED=true.
  4. The canonical URL defaults to https://<project>.pages.dev/. Set CLOUDFLARE_SITE_URL when a custom domain becomes production.

The workflow pins Hugo Extended 0.168.0, reads Go from go.mod, disables local module workspaces, and builds with Hugo Extended 0.168.0 and visible warnings before upload. It is the recommended reproducible path for Starter users.

You can also use Cloudflare Git integration as a separate mode. Set the build command to hugo --gc --minify --printPathWarnings, the output directory to public, Hugo to 0.168.0, and Go to 1.27. For one project, use either Git integration or the Direct Upload workflow, and build preview deployments with their own preview URL and a non-production environment so they remain unindexed.

Netlify — build command hugo --gc --minify, publish directory public, environment variable HUGO_VERSION. The same settings can live in the repository:

netlify.toml
[build]
command = "hugo --gc --minify --printPathWarnings "
publish = "public"

[build.environment]
HUGO_VERSION = "0.168.0"

If the theme is a submodule, enable recursive submodule checkout. For a Hugo Module, install Git and Go in the build environment. Use the same Hugo version for production and preview, unless the preview tests an upgrade.

Vercel — set the build command to hugo --gc --minify, the output directory to public, and environment variable HUGO_VERSION. No npm install is required.

Any static server (Nginx / Caddy) — serve an unchanged copy of public/. The example below uses a current symlink to a release directory; create it with the offline packaging steps below. Set the host’s document root to that link when configuring Nginx or Caddy:

/etc/nginx/conf.d/docs.conf
server {
    listen 80;
    server_name docs.example.com;
    root /var/www/oink/current;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    error_page 404 /404.html;
}

The site is purely static; there is no path to forward to an application server.

Object storage — Hugo has a deploy command; put the target in the configuration:

hugo.yml
deployment:
  targets:
    - name: aws
      URL: 's3://www.your-domain.tld'
      cloudFrontDistributionID: E9RZ8T1EXAMPLEID

After a build, run hugo deploy. It compares the remote output with public/ and uploads only changed files. If you supply cloudFrontDistributionID, it also invalidates the CDN cache. Without --target, it uses the first target. Use --dryRun first to inspect the proposed changes.

Two prerequisites apply. The Hugo binary must be built withdeploy, as shown by hugo version. Supply cloud credentials through the standard environment variables or configuration file. On AWS, first confirm access with aws s3 ls.

Offline packaging — for a network-isolated environment, build on a connected machine. Transfer the output as one package. Choose your archive path and use a new release name for every artifact. On the Linux host, you need write access to /var/www/oink and GNU mv. The path current must be absent or a symlink. The path current.next must not already exist. Configure Nginx or Caddy to serve current, as shown above. Configure this on the host, not in Hugo.

Terminal
hugo --cleanDestinationDir --gc --minify --baseURL "https://docs.internal.example.com/" &&
  tar -czf oink-site-20260929-01.tar.gz -C public .

After the build and packaging succeed, transfer the archive to the Linux host. Run the following commands there. Use a new release name for every artifact:

Linux host
release_dir=/var/www/oink/releases/20260929-01
mkdir -p /var/www/oink/releases
mkdir "$release_dir" &&
  tar -xzf oink-site-20260929-01.tar.gz -C "$release_dir" &&
  test -f "$release_dir/index.html" &&
  ln -s "$release_dir" /var/www/oink/current.next &&
  mv -Tf /var/www/oink/current.next /var/www/oink/current

The command chain switches current only after it creates a new directory, extracts the archive successfully, and confirms that index.html exists. Then check the deployed pages. Retain the previous release directory for rollback. Never unpack a release over an existing release directory.

Use the target environment’s baseURL for the initial build. If you change it, build again.

A host without Go — the Hugo Module method requires Go in the build environment. If the platform does not provide Go, use a Git submodule or an offline archive. For a submodule, run git submodule update --init before the build. For an archive, commit themes/oink/. See From scratch and other install methods.

Keeping preview deployments unindexed

Hugo’s -e / --environment selects build-time behavior. It does not change site content. Three OINK outputs depend on this setting. Only production emits <meta name="robots" content="index, follow">, writes Allow: / in robots.txt, and renders the Google Analytics template. Do not build PR previews or staging with --environment production:

Terminal
hugo --gc --minify --environment staging --baseURL "$PREVIEW_URL"

The output then carries noindex, nofollow and Disallow: /, and reports nothing to an analytics service.

Content Security Policy

The bundled runtimes, fonts, and icons are same-origin assets. However, script-src 'self'; style-src 'self' alone does not cover a normal OINK page. The theme emits inline theme initialization and shell prepaint scripts. It also emits inline styles for the initial canvas, theme colors, and font roles. Some components have style attributes. Markmap adds inline configuration and styles.

The theme provides no general policy, automatic CSP hashes, or nonce injection. The deployment must define its policy from the actual built output.

Additional features change the directives needed:

  • Inline HTML and inline scripts written by authors, which are the author’s responsibility under renderer.unsafe: true.
  • ECharts $fn: callbacks: the site registers callback functions on window.OinkEchartsFunctions. Include the registering script’s origin in script-src.
  • Analytics scripts: the script the site inserts, and the destination it reports to.
  • Local PlantUML rendering in OINK 1.4.0 needs same-origin scripts, wasm-unsafe-eval in script-src for WebAssembly compilation, and blob: in img-src. It needs no rendering-service origin.
  • Remote API specifications and self-hosted diagram services: these require permissions in connect-src and img-src.
  • giscus: script-src and frame-src must both permit it.
  • Duo view: panes are same-origin frames, so frame-src (or child-src) must allow 'self', and responses must allow same-origin framing (no X-Frame-Options: DENY or frame-ancestors 'none'). Enabling it adds one inline bootstrap script to every HTML page, which changes the script hashes.

Hash each permitted inline script/style block from the final deployed bytes, or have the host inject a fresh nonce into the response policy and corresponding tags. Because a <style> nonce does not authorize style="..." attributes, handle inline style attributes separately under style-src-attr. Recheck hashes after changes to content, configuration, minification, or the theme. Start with Content-Security-Policy-Report-Only and verify light/dark startup, shell state, menus, and every enabled component in the browser before enforcing the policy.

Start with a minimal policy that covers only reviewed features. Add permissions one at a time. If ECharts needs no callback, keep its options as pure data. Review inline scripts written by authors. Add a remote origin only for an integration that the site explicitly enabled. First, you can scan output subresource origins with the script in Verifying an offline build.

Acceptance checklist

After deployment, complete this table. The first four checks concern build-time output. Check the remaining items at the real URL.

A successful build with reviewed diagnostics
The build command carries --printPathWarnings and the log has Total in …; the upstream LibSass warning is accepted
baseURL is correct
<link rel="canonical"> in the page source points at the real production address, subpath included
Sitemap
<baseURL>/sitemap.xml resolves; a multilingual site has an index pointing at /en/sitemap.xml and /zh/sitemap.xml
robots
<baseURL>/robots.txt reads Allow: / with a Sitemap: line; a preview deployment should read Disallow: /
Search index
With local search enabled, the URL from data-td-index-src returns 200; production filenames contain a hash, and site search returns results
Markdown output
Appending index.md to any page URL returns plain text (where the site enabled markdown under outputs.page)
llms.txt
The primary and every enabled language root publish llms.txt where the site enabled LLMS under outputs.home
Enabled languages
Documentation, blog and home pages open in each, and switching language lands on the corresponding page rather than the home page
Appearance and interaction
The light/dark toggle, the print view and representative components (callouts, tabs, code block copy) all work
404
Visiting a path that does not exist shows the site’s own 404 page

The switches for sitemap.xml, robots.txt, .md and llms.txt are in Configuration, and the agent output details are in AI-agent support.

Rollback

To roll back a static site, republish the last known-good commit. Never edit production files by hand.

  • GitHub Pages: find the last successful Deploy to GitHub Pages run in Actions. Click Re-run all jobs. Alternatively, use git revert on the faulty commit and push again.
  • Cloudflare Pages / Netlify / Vercel: pick the last successful deployment from the list and use the platform’s Rollback / Publish deploy to make it production again.
  • A self-hosted static server: point current to the previous release directory from offline packaging. Do not extract the old archive over the new files. Paths added by the newer release would remain live.

On the Linux host, replace the example path with the retained known-good release. The same symlink and GNU mv prerequisites apply:

Terminal
previous_release=/var/www/oink/releases/20260928-01
test -d "$previous_release" &&
  ln -s "$previous_release" /var/www/oink/current.next &&
  mv -Tf /var/www/oink/current.next /var/www/oink/current

Check a representative old page at the public URL and confirm that a path added only by the rejected release is no longer served.

If a theme upgrade caused the problem, roll back the version pin in go.mod. See Upgrade.

  • Local preview — the full production build command, clearing caches and offline verification
  • Troubleshooting — 404s, empty search, platform-specific faults
  • Analytics and SEO — being indexed correctly after launch
  • Upgrade — upgrading the theme version and rolling back
  • Configuration — baseURL, outputs and the other site keys

3 - Comments

Use giscus for page comments through GitHub Discussions. Control comments for the site or a page, and match light and dark themes.

OINK uses giscus for comments. Each page maps to one GitHub Discussion. Readers sign in with a GitHub account to post comments. Maintainers moderate comments in GitHub Discussions. The theme has no comment backend of its own. It bundles only giscus.

You must use a public GitHub repository. Visitors cannot read a private repository’s Discussions.

This is one of the few features in the theme that makes an outbound request

A page with comments enabled loads a script and an iframe from https://giscus.app, which does not work in a network-isolated environment. Comments are off by default. They load only when you explicitly enable them. If the site has a privacy policy, document this external data boundary in it.

Preparing the GitHub repository

  1. Choose a public repository for the comment threads. You can use the site’s source repository.

  2. In the repository’s Settings → General → Features, select Discussions.

  3. Install the giscus GitHub App for that repository. Without the App, visitors cannot comment or react.

  4. Choose a Discussion category. giscus recommends the Announcements type. Only maintainers and the giscus bot can open a Discussion there. Readers cannot start one accidentally.

The repository ID and category ID are public identifiers, not credentials. Never put a personal access token, an OAuth secret or a password in Hugo configuration.

Generating the configuration

Open giscus.app. Enter the repository, mapping, and category. The page generates a <script> block below. Copy four attributes from that block to the OINK configuration:

data-repo
repo
data-repo-id
repoId
data-category
category
data-category-id
categoryId

The mapping determines which Discussion corresponds to each page. OINK defaults to pathname. This suits stable published paths and one repository that serves several domains or preview environments.

If you change mapping or move a page after comments exist, giscus searches for a different Discussion. It does not delete existing comments, but the page can no longer find them. Choose the mapping before launch. If a URL must change, retain a redirect or rename the Discussion at the same time.

Enabling it site-wide

Copy all four repository/category fields from the configuration generated for your repository. Before you enable comments, replace every placeholder below:

hugo.yml
params:
  comments:
    enable: true
    type: giscus
    giscus:
      repo: YOUR_OWNER/YOUR_REPO
      repoId: YOUR_REPO_ID
      category: YOUR_CATEGORY
      categoryId: YOUR_CATEGORY_ID
      mapping: pathname
      inputPosition: bottom
      theme: auto
      loading: lazy

The required fields repo, repoId, category, and categoryId must describe the same repository and its selected Discussion category. If a field is missing or contains only whitespace, Hugo prints one WARNING and skips giscus. The build succeeds with a warning. Review production build diagnostics and correct missing values before publication.

Currently, type accepts only giscus. Any other value also produces a warning and skips giscus. The params.comments key names match Hextra’s. A configuration migrated from Hextra can therefore remain unchanged.

The remaining keys (strict, reactionsEnabled, emitMetadata, term, lang, lightTheme, darkTheme, ariaLabel, errorMessage) all have defaults, defined fully in Configuration. A feature switch takes either a YAML boolean or giscus-style 0 / 1.

Per-page control

The front matter comments value can enable or disable comments regardless of the site switch. The value nearest the page takes precedence.

To enable comments only on selected pages, disable the site switch. Keep the complete repository configuration. Then enable comments on each selected page:

content/blog/2026-roadmap.md
---
title: 2026 roadmap
comments: true
---

To disable comments on selected pages, keep the site switch enabled. Then disable comments on each selected page:

content/about/security.md
---
title: Security policy
comments: false
---

Use a cascade to configure an entire section. This site sets comments: true in the cascade of content/docs/_index.md. Therefore, a giscus section appears at the end of this page.

content/docs/_index.md
---
title: OINK Documentation
cascade:
  type: docs
  comments: true
---

If the site also configures services.disqus.shortname, active giscus suppresses Disqus. The setting comments: false disables both. If a required giscus key is missing, the theme warns and skips giscus. Disqus can then load.

Multilingual text

The giscus interface automatically uses the current Hugo language. Simplified, Traditional, and Hong Kong Traditional Chinese each use the corresponding giscus locale. Unsupported languages fall back to English. Set lang explicitly only if the automatic choice is incorrect.

Translate OINK’s two comment strings: the section’s accessible label and the loading-failure message. Configure them per language. The theme merges them with the global repository configuration:

hugo.yml
languages:
  en:
    params:
      comments:
        giscus:
          ariaLabel: Comments
          errorMessage: Comments could not be loaded. Please try again later.
  zh:
    params:
      comments:
        giscus:
          ariaLabel: 评论
          errorMessage: 评论加载失败,请稍后重试。

A language layer needs only the values that differ. Keep repo / repoId / category / categoryId in params.comments.

Following light and dark

With theme: auto, the giscus iframe follows OINK’s light/dark control and the browser’s prefers-color-scheme. The comment section changes with the page.

To match the site’s palette more closely, set two giscus themes with lightTheme / darkTheme. Each value can be a built-in giscus theme name or CSS hosted by the site. This site uses hosted CSS:

hugo.yml
params:
  comments:
    giscus:
      theme: auto
      lightTheme: /css/giscus-oink-light.css?v=0.4.0
      darkTheme: /css/giscus-oink-dark.css?v=0.4.0

If you set a fixed theme name in theme, giscus no longer follows the toggle.

A custom giscus theme has to be readable cross-origin

The giscus iframe loads from giscus.app. CORS must permit it to read a CSS file from your site. For local preview, this site adds Access-Control-Allow-Origin: '*' under server.headers in hugo.yml. For production, configure this response header on the host.

Privacy and CSP

  • OINK never requests or stores a reader’s GitHub password or access token. All sign-in and posting operations occur on giscus / GitHub.
  • The theme ships the comment initialization script as a same-origin asset. It adds the script only to pages with comments enabled.
  • With loading: lazy, the iframe loads only as the reader scrolls near the comment section.
  • If the site has a strict Content Security Policy, both script-src and frame-src must permit giscus. Merge these permissions into the existing policy. Do not replace other directives. See Content Security Policy for the general rules:
CSP fragment
script-src 'self' https://giscus.app;
frame-src 'self' https://giscus.app;

If the external script fails to load or creates no iframe, OINK ends the loading state. It shows errorMessage in a live status region. The page does not remain on “loading”.

Verify

Terminal
hugo --minify # a missing required key warns and disables comments
hugo server --disableFastRender

Then check the following items:

  1. Open a page that should have comments. Confirm that giscus appears at the end with “Sign in with GitHub”. Its interface must use the current page’s language.
  2. Toggle OINK’s light/dark control. With theme: auto, confirm that the comment section follows it.
  3. Open a page with comments: false. Confirm that neither giscus nor another comment component appears.
  4. Post a test comment. Return to GitHub. Confirm that a Discussion appears in the selected category and that you can manage it there.

Before the first comment or reaction creates a Discussion, a browser console message saying the Discussion was not found is expected.

If comments do not work, check WARNINGs in the build log for the four required keys. Then check params.comments.enable and type, followed by the page’s comments front matter. Confirm that the repository is public, Discussions are enabled, and the giscus App is installed. Finally, check the browser console and response headers for a CSP block on giscus.app. If existing threads are missing, first restore the original mapping and page path.

4 - Analytics and SEO

Configure an optional analytics service. Check the canonical URLs, hreflang links, social cards, sitemap, and robots output that the theme generates.

By default, the theme loads no analytics, form, or advertising script. It makes no outbound request until you configure one. You must explicitly configure each integration. Document this external data boundary in the site’s privacy statement.

The theme automatically generates canonical links, hreflang links, the robots meta tag, Open Graph cards, and Twitter cards for each page. Set baseURL and each page’s description correctly.

Connecting Google Analytics

Use Hugo’s built-in service configuration. Replace G-YOUR_MEASUREMENT_ID with your own GA4 measurement ID before enabling this block:

hugo.yml
services:
  googleAnalytics:
    id: G-YOUR_MEASUREMENT_ID

The theme renders this script only in the production environment. A normal hugo server uses development and sends no analytics reports. A hugo build defaults to production, including on a preview host. For PR and staging deployments, select a non-production environment. Set PREVIEW_URL to the deployment’s actual address:

Terminal
hugo --environment staging --baseURL "$PREVIEW_URL"

See preview deployment settings.

Do not also set the deprecated top-level googleAnalytics key. If you do not want analytics, delete the block. Do not enter a fake ID.

This is incompatible with a network-isolated environment

When you configure this integration, it sends page views and events to Google. A strict same-origin Content Security Policy must also permit it. See Content Security Policy. The site must choose to enable this integration. The theme does not enable it by default.

Connecting another analytics service

To connect Plausible, Umami, Matomo, or a similar service, insert its script. The theme provides two injection points. Create a file with the corresponding name in the site repository. You do not need to change the theme:

layouts/_partials/hooks/head-end.html , Insertion pointBefore </head>, ahead of the Google Analytics template
Analytics scripts, cookie consent scripts, meta tags the theme does not provide
layouts/_partials/hooks/body-end.html , Insertion pointLast among the page scripts
Third-party code that affects interaction instead of the first paint

For Plausible, replace your-site.example with the domain registered in your own account before adding this hook:

layouts/_partials/hooks/head-end.html
{{ if hugo.IsProduction }}
<script defer data-domain="your-site.example"
        src="https://plausible.io/js/script.js"></script>
{{ end }}

Do not omit the hugo.IsProduction guard. Without it, each local preview sends reports to your analytics service.

head-end runs before Google Analytics

A cookie consent script must run before the analytics script. This order lets the consent script prevent analytics from running.

The “was this page helpful?” feedback widget is separate. It is off by default and makes no network request. Configure it as described in Repository links and page info.

Duo view panes

With params.ui.compare enabled, opening the duo view loads both pages inside same-origin frames. Theme-managed analytics (services.googleAnalytics.id and params.analytics.*) skips those panes automatically so opening the reader does not double-count page views. When params.ui.compare: true is active, OINK renders the Google Analytics snippet through its own pane-aware template rather than Hugo’s built-in partial, so a site override at layouts/_partials/google_analytics.html will not take effect.

Custom scripts in head-end.html still execute on every frame load. Guard them with window.OinkComparePane before recording a page view:

layouts/_partials/hooks/head-end.html
{{ if hugo.IsProduction }}
<script>
  if (!window.OinkComparePane) {
    var script = document.createElement('script');
    script.defer = true;
    script.dataset.domain = 'your-site.example';
    script.src = 'https://plausible.io/js/script.js';
    document.head.appendChild(script);
  }
</script>
{{ end }}

Server and CDN analytics also see pane requests. They carry the query oink_compare_pane=1 and can be filtered out.

Page descriptions

<meta name="description"> takes the first non-empty value of:

  1. The page’s description front matter
  2. The page summary Hugo computes (.Summary)
  3. params.description in the site configuration

Authors need only write one description per page for SEO. It supplies the search engine snippet, the card subtitle on a section index, and the result preview in site search.

content/docs/admin/analytics.md (this page)
---
title: Analytics and SEO
description: Connect an analytics service (or none), and pair up the canonical, hreflang, social cards, sitemap and robots the theme already generates.
---

For a multilingual site, write one description per language. Do not copy the English description to a Chinese page. Set the site-level default per language too:

hugo.yml
languages:
  en:
    params:
      description: A Hugo theme for engineering docs
  zh:
    params:
      description: 为工程而设计的 Hugo 文档主题

canonical and hreflang

The theme emits one canonical link per page and hreflang alternate links for actual translations. No configuration is required:

rendered output (this page)
<link rel="canonical" href="https://oink.pgsty.com/docs/admin/analytics/">
<link rel="alternate" hreflang="en-US" href="https://oink.pgsty.com/docs/admin/analytics/">
<link rel="alternate" hreflang="zh-CN" href="https://oink.pgsty.com/zh/docs/admin/analytics/">

The hreflang codes use each language’s locale (en-US / zh-CN on this site) and follow Hugo’s translation graph. Since OINK 1.2.0, untranslated pages omit hreflang and og:locale:alternate tags even when the visible language switcher links back to the target language’s home page.

Each paginated Blog index page uses its own canonical URL, and pages 2 and above omit hreflang alternate links because pagination boundaries can differ between languages. (OINK 1.1.0 retained the earlier behavior.)

The canonical URL uses baseURL. An incorrect baseURL directs search engines to addresses that do not exist. This problem is less visible than a build failure. Complete the deployment checklist before launch.

Full multilingual configuration is in Languages.

Social cards

The theme calls Hugo’s built-in Open Graph and Twitter card templates. They automatically supply the title, description, URL, language, and site name:

rendered output (this page)
<meta property="og:title" content="Analytics and SEO">
<meta property="og:type" content="article">
<meta property="og:url" content="https://oink.pgsty.com/docs/admin/analytics/">
<meta property="og:locale" content="en_US">
<meta property="og:locale:alternate" content="zh_CN">
<meta name="twitter:card" content="summary">

To give a shared link an image, set images in front matter:

any page
---
title: OINK v0.8.0 released
images: [/images/releasenote.webp]
---

For a site-wide fallback, write the same key under params:

hugo.yml
params:
  images: [/images/oink.webp]

When an image is present, twitter:card changes from summary to summary_large_image. The output also includes og:image and twitter:image. This site sets neither image key, so the output above has no image tags.

Sitemap

Hugo automatically generates the sitemap. For a multilingual site, it generates an index:

the structure under public/
sitemap.xml        ← the index, pointing at the two below
en/sitemap.xml
zh/sitemap.xml

Both the site default and per-page overrides are Hugo’s own:

hugo.yml
sitemap:
  changefreq: monthly
  filename: sitemap.xml
  priority: 0.5
one page
---
title: Release notes
sitemap:
  priority: 0.8
---

changefreq and priority are hints. A search engine may ignore them. Before publishing, confirm that the sitemap excludes drafts, private content, and non-canonical copies. Confirm that Hugo generated a file for each language.

robots.txt and staying unindexed

Hugo generates robots.txt only when the site configuration turns it on:

hugo.yml
enableRobotsTXT: true

The theme’s template generates one of two results, based on the build environment. You do not need to write the content:

a production build
User-agent: *
Allow: /

Sitemap: https://oink.pgsty.com/sitemap.xml
a non-production build
User-agent: *
Disallow: /

The page’s robots meta tag uses the same switch. It emits index, follow in production, except in print output. Otherwise, it emits noindex, nofollow. Do not build preview deployments with --environment production. A non-production build automatically requests no indexing.

The theme has no per-page noindex switch. To reliably prevent indexing, do not publish the page. Use draft: true or Hugo’s _build options. If you must publish it and request no indexing, emit your own tag through the head-end.html hook. The theme already emits one robots meta tag. Each search engine decides how to interpret two tags.

Checking indexing

One or two weeks after launch, check the following items in order. Confirm that search engines see the expected site:

  1. Crawl permission: open <baseURL>/robots.txt. Confirm that it contains Allow: / instead of Disallow: /.
  2. Page inventory: open <baseURL>/sitemap.xml. Open a language sitemap from the index and check the page count.
  3. Indexed count: search site:yourdomain. Check the order of magnitude. You do not need to compare every page.
  4. Canonical addresses: confirm that results open the canonical URL. They should not use a ? parameter or an old domain.
  5. Active submission: add the site in Google Search Console / Bing Webmaster Tools. Submit the sitemap.xml address to request crawling sooner.

Verify

Run from your site’s root. Replace PAGE with a generated page on your site, including any language prefix:

Terminal
hugo --gc --minify --printPathWarnings
PAGE=public/docs/getting-started/index.html
test -f "$PAGE"

# Canonical should use the real production address; production robots allow indexing.
grep -o '<link[^>]*canonical[^>]*>' "$PAGE"
grep -o '<meta[^>]*robots[^>]*>' "$PAGE"
cat public/robots.txt
head -5 public/sitemap.xml

# No match is expected when Google Analytics is not configured.
grep -o '<script[^>]*googletagmanager[^>]*>' "$PAGE"

In the browser’s Network panel, confirm that configured analytics requests use your measurement ID or registered domain. Repeat this check on a deployment built with --environment staging. It should make no analytics request. If you configured no analytics, neither environment should make an analytics request. Other explicitly enabled integrations may still contact their remote services.

  • Deploy — baseURL, the checklist, and keeping preview deployments unindexed
  • Repository links and page info — the feedback widget, edit links and last-modified time
  • Languages — language configuration decides hreflang and translation pairing
  • AI-agent support — the .md output and llms.txt written for models
  • Configuration — services, sitemap, enableRobotsTXT and the rest

5 - Upgrade

Pin a theme version, upgrade to 1.5.1, migrate legacy content or a Docsy site, and keep a rollback path.

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.

Current Hugo baseline

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: false for any language that should neither display the reader nor appear as a target language.
  • Guard custom analytics snippets in head-end.html with window.OinkComparePane so pane loads are not counted twice. Note that a local override of Hugo’s google_analytics.html partial is not used when compare is 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 with X-Frame-Options: DENY or frame-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

Local PlantUML in OINK 1.4.0

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 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:

Terminal
hugo mod get github.com/pgsty/[email protected]   # the published release tag
hugo mod tidy
hugo mod graph | grep github.com/pgsty/oink

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:

go.mod
module github.com/pgsty/oink.pgsty.com

go 1.27.3

require github.com/pgsty/oink v1.5.1
A local module replacement overrides that pin

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:

Terminal
git -C themes/oink fetch origin --tags
git -C themes/oink checkout --detach v1.5.1
git add themes/oink

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

Terminal
rm -rf public resources/_gen
env -u HUGO_MODULE_REPLACEMENTS GOWORK=off HUGO_MODULE_WORKSPACE=off \
  hugo --gc --minify --printPathWarnings --logLevel info

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.
Groups
sidebar_divider: true retains a section’s children. Add build.render: never only if you intentionally omit the group’s own outputs. Verify child navigation, breadcrumbs, paging, Print, and Book contents.
Root menus
Explicit sidebar_root_menu: false now applies to self-root sections too. The current linkable root remains a location marker.
Custom scripts
Feature-detect OinkSidebar and OinkCommandPalette.registerSearchTail if an integration must also support 1.0.0. Restore branch state through the API rather than changing classes or ARIA attributes directly.
Copying articles
With image zoom enabled, copy an image and its caption as plain text and rich HTML. Preview instructions must not enter the copied article. Zoom and its keyboard controls must still work.
Print and Redoc
Check page and Book aggregate Print, heading and tab links, and local Redoc specifications under the real deployment prefix. Local specification paths are rooted under static/.

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:

Terminal — from oink.pgsty.com
make check
make browser
make dev

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

Default appearance change

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: false or params.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:

Terminal
git clone https://github.com/pgsty/oink
cd oink

# 1. read-only inventory: what several sites would change, exportable as Markdown / JSON
python3 bin/migrations/oink06.py report --sites ~/pgsty/oink.pgsty.com ~/www/ddia --md report.md

# 2. dry run: prints a diff and counts per file, writing nothing
python3 bin/migrations/oink06.py migrate --site ~/pgsty/oink.pgsty.com

# 3. apply: written atomically
python3 bin/migrations/oink06.py migrate --site ~/pgsty/oink.pgsty.com --write

# 4. check for residue: exit code 1 while legacy syntax remains
python3 bin/migrations/oink06.py check --site ~/pgsty/oink.pgsty.com

Follow these four rules when you use the tool:

  • A dry run is the default. Only --write changes files. Run the dry run, read the diff, and then write.
  • A second run should change nothing. If a second --write reports 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:line and 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:

Terminal
python3 bin/migrations/oink06.py migrate --site ~/www/ddia --only callout,tabs --write

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

{{%/* alert color= title= */%}}, {{%/* details */%}}, {{%/* pageinfo */%}}, hand-written <details><summary> , The current form> [!TYPE] Title / > [!DETAILS]-
callout
{{</* tabpane */>}} + {{%/* tab header= */%}}, {{</* code-group */>}} + {{</* code-tab */>}} , The current formAdjacent fences with {tab= group= value=}; tabs in running text use {{</* tabs */>}} + {{</* tab */>}}
tabs
{{</* filetree */>}} with filetree/folder and filetree/file , The current formThe filetree data fence
filetree
{{</* gallery */>}} with gallery/image , The current formThe gallery data fence
gallery
{{</* echarts */>}}, {{</* infographic */>}} , The current formData fences of the same name ($fn: is unchanged; a js subfence moves to window.OinkEchartsFunctions)
datafence
doc-cards / doc-card, nav-cards / nav-card, card / cardpane, doc-carousel , The current form{{</* cards */>}} + {{</* card */>}}, or a link list with {.cards}
cards
{{</* imgproc */>}}, {{</* image */>}} , The current form![alt](src) with the attribute line {command= options= caption=}
image
{{</* readfile file= */>}} , The current form{{</* include file= */>}}
include
The fence attribute {filename="x"} , The current form{title="x"}
fencetitle
{{</* badge outline= */>}} , The current formDrop the outline parameter
badge
{{</* example */>}} + a fence, {{</* book-figures kind="tbl" */>}} , The current form{{</* eg */>}}…{{</* /eg */>}}, {{</* book-tables */>}}
eg
{{%/* _param x */%}}, iframe, conditional-text, blocks/*, netlify, a kindless xref , The current formReported only; handle by hand
reportonly

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.

  1. Pin the target version. Change go.mod to an OINK release tag, or use a complete versioned archive. During evaluation, an uncommitted go.work can point at a local checkout.

  2. Inventory the overrides. Classify each site-level file under layouts/, assets/, and static/ 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 empty layouts/ at once. The home page or download page may still call a partial that you plan to remove.

  3. Move the configuration. Keep title, languages.*, github_repo, github_branch, page_width, and params.ui.* in their existing semantic positions. OINK adds no separate namespace. Enable search and the logo with these keys:

    hugo.yml
    params:
      logo: img/product.svg
      offline_search: true

    Docsy’s camelCase search keys have been renamed in OINK: offlineSearch, offlineSearchIndex, offlineSearchMaxResults, offlineSearchOnServe and offlineSearchSummaryLength all 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.

  4. Fonts and styling compatibility. The Docsy Sass variables in assets/scss/_variables_project.scss still 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-code supplies 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.

  5. Convert the shortcodes. Docsy’s alert, pageinfo, tabpane and card families all have a current counterpart; convert them in bulk with the migration toolkit above, one --only class at a time.

  6. 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.html and the shared docs / blog baseof*.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 and param shortcodes;
  • 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:

layouts/_partials/hooks/head-end.html
<script src="{{ (resources.Get "js/jquery.min.js").RelPermalink }}"></script>

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, and blog pages have previous / next links at the page end. Documentation follows the sidebar tree. Blog pages follow time. For a page intentionally outside a sequence, set pager: 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: false in a cascade.

  • The footer defaults to fat for the site. It accepts only fat / slim / none. Store footer data in data/footer/<language>.yaml, or data/footer.yaml for a single-language site. A remaining footer key in data/home produces 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-code wrapper now encloses the original .highlight. Both .highlight and .chroma remain. In site CSS, replace a direct child selector such as .td-content > .highlight with the descendant selector .td-content .highlight.

  • Two ICP footer parameters were removed. The keys footer_icp and footer_icp_url became one string that accepts inline Markdown.

    hugo.yml
    params:
      footer_center_info: '[京ICP备00000000号](https://beian.miit.gov.cn/)'
  • For mathematics, enable passthrough in the site. Hugo does not merge a theme’s markup configuration. If the site uses \(…\), \[…\], or $$…$$, enable Goldmark passthrough in its own hugo.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:

Documentation / Book
Sidebar order, paging, headings, page actions, numbering and cross-references
Blog
Chronological paging, RSS ownership, navbar and footer
Home / landing
Content without JS, the compact menu, print
Release pages
Derived download URLs, checksums, publication state
Components
One page each for the components the site uses most
Accessibility
Keyboard-only operation, focus order, both color schemes, forced-colors mode
Deployment
Internal links and assets all keep the base path prefix

This site’s full gate is:

Terminal
make check     # local sibling theme: build, outputs, translations, and rendered links
make browser   # local sibling theme: accessibility, responsive and interactive behavior
make build     # published theme pinned in go.mod, without a local replacement

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:

Terminal
hugo mod get github.com/pgsty/[email protected]   # example: the site's last known-good tag
hugo mod tidy
rm -rf public resources/_gen
hugo --gc --minify

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.

6 - Troubleshooting

Diagnose build, language, search, and platform problems by symptom, cause, and fix. Run checks on your site.

If a problem occurs, first run a clean production build. Read the first error. Later errors usually result from it:

Terminal
rm -rf public resources/_gen
hugo --gc --minify --printPathWarnings --logLevel info

If the log includes an npm, PostCSS, Autoprefixer, or browser-asset download step, the configuration still uses upstream Docsy’s process. An OINK consumer build requires one Hugo command.

The four tables below show each symptom, its cause, and its fix. Find the row for your symptom. You do not need to read every row.

Build

Symptom Cause Fix
The build demands a newer Hugo Hugo Standard is installed instead of Extended, or the version is below 0.168.0 hugo version output must contain extended. If several Hugo versions are installed, check PATH and version pins before installing another
module "github.com/pgsty/oink" not found The theme did not resolve Hugo Module: check hugo mod graph, go.mod, go.sum, and unexpected workspaces or replacements. Submodule: confirm that CI runs git submodule update --init before Hugo. Archive / clone: theme: must match the directory name under themes/
Module download hangs or times out The Go module proxy is unreachable Hugo downloads modules through Go, so GOPROXY applies. In mainland China, use export GOPROXY=https://goproxy.cn,direct. In an isolated environment, use an offline archive or commit themes/oink/
{.cards}, {.steps}, {caption=…} appear as literal text The site has not enabled Goldmark block attributes Put all three settings below in the site’s own hugo.yml. Hugo does not merge a theme’s markup configuration
An image with an attribute line is wrapped in <p> and the caption does nothing wrapStandAloneImageWithinParagraph: false is missing Add all three settings below together
Inline HTML is escaped into text renderer.unsafe: true is missing As above
\(…\) $$…$$ display literally The site has not enabled Goldmark passthrough See Math. The setting math: true does not enable passthrough
shortcode "tabs" must be closed or self-closed A {{< tabs >}} has no matching {{< /tabs >}} The error identifies file:line:column. Add the closing marker at that location
template for shortcode "tabs" not found The body calls a shortcode that does not exist, or quotes shortcode syntax without escaping it Documentation that explains shortcode syntax must escape it. Add /* and */ inside the opening and closing markers. Hugo then treats it as text instead of a call. If the name is misspelled, correct it
... attributes: unknown attribute "witdh" at ... An attribute-line key is misspelled or not permitted The warning lists allowed keys. The theme ignores the invalid attribute and drops style and on*. Correct the attribute
shortcode "field": unsupported parameter "colour" at ... A shortcode parameter name is wrong The warning identifies the shortcode, parameter, file, and line. The theme ignores the unsupported parameter so preview remains usable; correct the parameter name
invalid params.ui.page_width "widee" (allowed: normal | wide | full) -- using "normal" A configuration or front matter value is not one of the accepted ones The theme uses a fallback instead of stopping so a typo does not produce HTTP 500 on every URL under hugo server. The message identifies the key, value, and fallback
A page setting has no effect and nothing is reported The key was written inside a ui: block in front matter Put page keys at the top level of front matter. Remove ui. from the site key. The theme ignores a front matter ui: block without reporting it. See Page parameters
The build passes but production is missing something An unreviewed WARNING Review the build warnings and correct invalid configuration values, missing required giscus keys, or unsupported comments.type values. The upstream LibSass deprecation warning is accepted

The three Goldmark settings:

hugo.yml
markup:
  goldmark:
    parser:
      wrapStandAloneImageWithinParagraph: false
      attribute:
        block: true
    renderer:
      unsafe: true

The two most common shortcode errors look like this. Each ends with file:line:column:

build output
ERROR error building site: assemble: failed to create page from pageMetaSource /a:
  "…/content/docs/x.md:4:1": failed to extract shortcode:
  shortcode "tabs" must be closed or self-closed

ERROR error building site: assemble: failed to create page from pageMetaSource /a:
  "…/content/docs/x.md:4:5": failed to extract shortcode:
  template for shortcode "tabs" not found

Language

Symptom Cause Fix
A translated page does not appear Four possibilities, in order ① hugo.yml has languages.zh with a weight; ② the filename is page.zh.md, with zh lowercase; ③ the translation’s front matter has no draft: true and no future date; ④ routing metadata matches the source file
Switching language lands on the home page Hugo found no translation If no translation exists, the switcher uses the target language’s home page. To open the corresponding page, add its translation file
An anchor link opens the page but does not scroll The translated heading text differs, so the generated ID does too Set the English ID explicitly on the translated heading: ## 安装 {#installation}. If a heading contains a shortcode or inline HTML, read its ID from the English page’s rendered HTML. Do not guess it
Menus / home page sections are untranslated They are not in pages but in configuration and data files Menus are in languages.<lang>.menus. Home sections are in data/home/<lang>.yaml. Interface strings are in i18n/<lang>.yaml. See Languages
A page’s hreflang points at another language’s home page The published 1.1.0 behavior or a copied older SEO partial can reuse the language-switcher fallback The 1.2.0 development implementation omits missing translations from SEO alternates. Check the resolved theme version and template overrides; add the corresponding page when a translation is intended. The visible language switcher’s home-page fallback remains valid
Symptom Cause Fix
A search box that never returns results No index was generated Check params.offline_search and open search. Inspect the page’s data-td-index-src URL in Network. Production uses offline-search-index.<language>.<hash>.json. Development omits the hash. If the index is absent during hugo server, also check offline_search_on_serve
The index file 404s A wrong baseURL For a subpath deployment, an incorrect baseURL is the most common cause of an index 404. Check the requested index URL in the browser’s network panel. See Deploy
Search fails under hugo server but works in a build The site turned the preview index off params.offline_search_on_serve defaults to true, so preview matches production. An explicit false skips preview index generation. Remove that setting or restore true
Chinese queries find nothing Usually not a tokenization problem A CJK query uses the theme’s substring fallback. First, open the Chinese page’s actual data-td-index-src URL. Confirm that the Chinese index contains its content. Then check tokenization
A new page is not found while old ones are The index is build output Rebuild. Under hugo server, wait for the rebuild after editing
params.search.algolia requires explicit appId, apiKey, and indexName values The three Algolia keys are incomplete All three must be given explicitly; the theme will not use another project’s DocSearch credentials. If Algolia is not wanted, delete the block
The command palette finds no content Command actions and full-text search are separate If the index is unavailable, the palette still opens and reports this condition. Page actions and commands still work. See Command palette

Platform

Symptom Cause Fix
A 404 or missing styles on GitHub Pages A project site’s URL carries the repository path and baseURL does not Use --baseURL "${{ steps.pages.outputs.base_url }}/" from the workflow. Do not hard-code the address. See the complete workflow in Deploy
“Last modified” and contributors are empty on GitHub Pages The checkout is shallow Add fetch-depth: 0 to actions/checkout. The setting enableGitInfo requires the complete history
A Cloudflare Pages build says Hugo is too old The build image’s default Hugo is older than the theme requires Set HUGO_VERSION in both the Production and Preview environments, and set SKIP_DEPENDENCY_INSTALL=1
The host’s build cannot fetch the theme The build environment has no Go Hugo Modules require Go. If the platform does not provide it, use a submodule or commit themes/oink/
CI output differs from local go.work took part in the CI build Set GOWORK: off and HUGO_MODULE_WORKSPACE: off in CI so it reads only the version pinned in go.mod
A preview deployment got indexed The preview was built in the production environment too Do not pass --environment production for previews. A non-production build emits noindex and Disallow: /. See Analytics and SEO
macOS reports too many open files Live preview watches more files than the shell limit allows First exclude generated and irrelevant directories from the watch. These usually cause the problem. Then, if necessary, consider ulimit -n
Slow, or missed changes, under WSL Working across a Windows mount point Run Hugo on paths inside the Linux filesystem. Cross-filesystem change notifications and permission behavior can break live reload
Bootstrap / Font Awesome / Lunr / Mermaid assets are missing An incomplete distribution Do not substitute a CDN URL. Confirm that assets/third_party/, assets/js/third_party/, static/webfonts/, and VENDOR.json are present. If a file is missing, download the same pinned version again

Checks a site can run

Run the build from your site’s root. Use the separate output checker from a theme checkout that matches your pinned release. Replace /path/to/oink, /path/to/my-site/public, and the base URL with your values. The remaining commands are examples from this documentation repository’s test harness. They are not supplied to every OINK consumer.

A production build , Commandhugo --printPathWarnings
Duplicate output paths, invalid parameters, incomplete external integrations
Output trust check , Commandpython3 /path/to/oink/bin/check-output-security.py --public /path/to/my-site/public --base-url https://my-site.example/
Checks every href / src in all four outputs for site-relative paths or http(s) / mailto / tel. Rejects javascript: URLs and inline on* handlers. A cross-site <iframe>, <script>, or <img> requires explicit --third-party
Translation parity , Commandnode scripts/check-doc-translations.mjs --public public
Checks that each English page has a Chinese counterpart and that rendered heading IDs match. Detects misaligned anchors
The full gate , Commandnpm test
Runs the six below in sequence

The six checks cover the following items:

  • test:base — builds once, then runs the Markdown style, translation parity, rendered Markdown and link checks.
  • test:hugo-build — build assertions: blog metadata, RSS, content components, and a deprecation-free build.
  • test:md-output — compares Markdown and llms.txt output byte for byte against goldens. A change to a component’s Markdown structure fails this check.
  • test:alt-site — builds once for each alternate configuration in tests/fixtures/*.yml. Confirms that each combination still works.
  • test:favicons — golden comparison of the head output.
  • test:release-pin-contract — whether the version the site advertises matches the one pinned in go.mod.

Browser behavior has a separate suite. The command npm run test:browser runs the Playwright accessibility (axe WCAG AA), responsive shell, keyboard navigation, content component, code block, and scenario component suites in sequence.

check-output-security.py lives in the theme repository

It sits under the theme’s bin/, is a product-level trust check any OINK site can run, and depends on no site test framework. Keep the theme-tool path and your site’s output path distinct; the complete example is in Verifying an offline build.

Diagnostic habits

If the tables do not cover the problem, use these diagnostic steps:

  • Reproduce the problem with a pinned Hugo Extended version. Avoid an environment with an unpinned version.
  • Clear public/ and resources/_gen and rebuild, to rule out stale caches.
  • Compare the development and production configuration layers; many production-only problems are environment differences.
  • Read the first error. Later errors may result from it.
  • Use a minimal page to distinguish “theme behaviour” from “site override”. Put the suspect content on its own page. Re-enable site overrides in batches until a batch causes the problem.
  • Look at the failing page’s browser console and network panel, especially the paths of any 404 resources.

Getting help

When you open an issue, include the complete hugo version output and the theme version from hugo mod graph | grep oink. Include the first complete error and a minimal page or site that reproduces it. This information avoids an additional request for details.

  • Local preview — clean builds, clearing caches, containers and workspaces
  • Deploy — baseURL, the checklist and rollback
  • Upgrade — problems an upgrade introduces, and the migration toolkit
  • Search — index scope, ranking and Algolia
  • Languages — language configuration and the anchor alignment process