This is the multi-page printable view of this section. .
Operations
- 1: Local preview
- 2: Deploy
- 3: Comments
- 4: Analytics and SEO
- 5: Upgrade
- 6: Troubleshooting
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
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):
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,- Also builds pages with
draft: true -F/--buildFuture,- Also builds pages whose
date/publishDateis in the future -E/--buildExpired,- Also builds pages whose
expiryDatehas passed --disableFastRender,- Re-renders the complete site on every change instead of using incremental rendering
-M/--renderToMemory,- Renders only in memory. Writes no
public/ -N/--navigateToChanged,- The browser opens the page you saved
--bind,- The listen address. Use
0.0.0.0for access from a LAN or outside a container -p/--port,- The listen port
--minify,- Minifies the preview too, to reproduce production rendering
--printPathWarnings,- Warns when two pages write to the same target path
The combination used while developing this site:
-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:
- Restart with
--disableFastRender. Check whether the change appears. - Force a browser refresh (
Cmd/Ctrl+Shift+R) to exclude browser cache as the cause. - 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:
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:
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/_genthat 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:
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
productionemits<meta name="robots" content="index, follow">. Other environments emitnoindex, nofollow. - In
production,robots.txtcontainsAllow: /. In other environments, it containsDisallow: /. - Only
productionrenders 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:
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.
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.
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/,- A deleted page remains live. You can also let the build clear this directory with
hugo --cleanDestinationDir resources/_gen/,- Image processing parameters, fonts, or the accent color changed, but the page still shows the old appearance
hugo mod clean,- The theme version changed, but the old version still resolves. Add
--allto clear the complete module cache
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:
This site’s Makefile wraps those commands and expects the theme checkout at
the sibling ../oink:
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:
- Start from a verified theme archive and an empty module cache (
hugo mod clean --all). - Block outbound HTTP, HTTPS and the Go module proxy.
- Run the production build
hugo --gc --minify --printPathWarnings. - Browse pages in both languages: a documentation page, a blog page, the home page, the 404.
- Exercise search, the light/dark toggle, diagrams and content components.
- 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:
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:
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/hassitemap.xmlandrobots.txt, androbots.txtreadsAllow: /.- If local search is enabled, confirm that each language has an index in
public/. Production filenames areoffline-search-index.<language>.<hash>.json. Development filenames omit the hash. Open search and confirm that the actualdata-td-index-srcURL 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.
Related
- Deploy — getting
public/to GitHub Pages, Cloudflare or elsewhere - Troubleshooting — the four common fault classes: build, language, search, platform
- From scratch and other install methods — weighing Hugo Module, submodule and offline archive
- Configuration — every key in
hugo.yml
2 - Deploy
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:
For deployment to a subpath (https://example.com/docs/), include that path in
baseURL:
You can also override this value at build time. This lets you deploy one source to several locations:
canonifyURLsKeep 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.
OINK Starter ships this workflow. The following settings are required:
fetch-depth: 0— ifenableGitInfois enabled, “last modified” and contributor information require the complete Git history. A shallow clone leaves them empty.setup-goplusgo mod download— Hugo needs Go to resolve the theme as a Hugo Module. For a submodule installation, usesubmodules: recursiveinstead. For an offline archive, committhemes/oink/. With either alternative, remove both Go steps.GOWORK: offandHUGO_MODULE_WORKSPACE: off— exclude a local developmentgo.workfrom the CI build. CI then verifies the published tag pinned ingo.mod.--baseURL "${{ steps.pages.outputs.base_url }}/"— a project site’s URL ishttps://<OWNER>.github.io/<REPO>/. Use the value computed byconfigure-pagesinstead of a hard-coded address. Warnings remain visible for review. Do not enable--panicOnWarningorHUGO_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.
- Create a Direct Upload Pages project. Its name defaults to the repository
name. To override it, set repository variable
CLOUDFLARE_PROJECT_NAME. - Add repository secrets
CLOUDFLARE_ACCOUNT_IDandCLOUDFLARE_API_TOKEN. The token needs Account → Cloudflare Pages → Edit. - Run Deploy to Cloudflare Pages manually once. To deploy every push to
main, set repository variableCLOUDFLARE_PAGES_ENABLED=true. - The canonical URL defaults to
https://<project>.pages.dev/. SetCLOUDFLARE_SITE_URLwhen 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:
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:
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:
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.
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:
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:
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 onwindow.OinkEchartsFunctions. Include the registering script’s origin inscript-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-evalinscript-srcfor WebAssembly compilation, andblob:inimg-src. It needs no rendering-service origin. - Remote API specifications and self-hosted diagram services: these require permissions in
connect-srcandimg-src. - giscus:
script-srcandframe-srcmust both permit it. - Duo view: panes are same-origin frames, so
frame-src(orchild-src) must allow'self', and responses must allow same-origin framing (noX-Frame-Options: DENYorframe-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
--printPathWarningsand the log hasTotal in …; the upstream LibSass warning is accepted baseURLis correct<link rel="canonical">in the page source points at the real production address, subpath includedSitemap<baseURL>/sitemap.xmlresolves; a multilingual site has an index pointing at/en/sitemap.xmland/zh/sitemap.xmlrobots<baseURL>/robots.txtreadsAllow: /with aSitemap:line; a preview deployment should readDisallow: /Search index- With local search enabled, the URL from
data-td-index-srcreturns 200; production filenames contain a hash, and site search returns results Markdown output- Appending
index.mdto any page URL returns plain text (where the site enabledmarkdownunderoutputs.page) llms.txt- The primary and every enabled language root publish
llms.txtwhere the site enabledLLMSunderoutputs.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 Pagesrun in Actions. Click Re-run all jobs. Alternatively, usegit reverton 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
currentto 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:
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.
Related
- 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,outputsand the other site keys
3 - Comments
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.
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
-
Choose a public repository for the comment threads. You can use the site’s source repository.
-
In the repository’s Settings → General → Features, select Discussions.
-
Install the giscus GitHub App for that repository. Without the App, visitors cannot comment or react.
-
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-reporepodata-repo-idrepoIddata-categorycategorydata-category-idcategoryId
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:
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:
To disable comments on selected pages, keep the site switch enabled. Then disable comments on each selected page:
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.
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:
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:
If you set a fixed theme name in theme, giscus no longer follows the toggle.
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-srcandframe-srcmust permit giscus. Merge these permissions into the existing policy. Do not replace other directives. See Content Security Policy for the general rules:
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
Then check the following items:
- 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.
- Toggle OINK’s light/dark control. With
theme: auto, confirm that the comment section follows it. - Open a page with
comments: false. Confirm that neither giscus nor another comment component appears. - 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.
Related
- Repository links and page info — edit this page, open an issue, contributors and the “was this helpful?” widget
- Analytics and SEO — the other capability needing an external service
- Deploy — Content Security Policy and external integrations in preview deployments
- Configuration — every
params.comments.*key - Page parameters —
commentsin front matter
4 - Analytics and SEO
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:
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:
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.
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,- Analytics scripts, cookie consent scripts, meta tags the theme does not provide
layouts/_partials/hooks/body-end.html,- 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:
Do not omit the hugo.IsProduction guard. Without it, each local preview sends
reports to your analytics service.
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:
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:
- The page’s
descriptionfront matter - The page summary Hugo computes (
.Summary) params.descriptionin 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.
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:
canonical and hreflang
The theme emits one canonical link per page and hreflang alternate links for
actual translations. No configuration is required:
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:
To give a shared link an image, set images in front matter:
For a site-wide fallback, write the same key under params:
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:
Both the site default and per-page overrides are Hugo’s own:
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:
The theme’s template generates one of two results, based on the build environment. You do not need to write the content:
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:
- Crawl permission: open
<baseURL>/robots.txt. Confirm that it containsAllow: /instead ofDisallow: /. - Page inventory: open
<baseURL>/sitemap.xml. Open a language sitemap from the index and check the page count. - Indexed count: search
site:yourdomain. Check the order of magnitude. You do not need to compare every page. - Canonical addresses: confirm that results open the canonical URL. They should not use a
?parameter or an old domain. - Active submission: add the site in Google Search Console / Bing Webmaster Tools. Submit the
sitemap.xmladdress to request crawling sooner.
Verify
Run from your site’s root. Replace PAGE with a generated page on your site,
including any language prefix:
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.
Related
- 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
hreflangand translation pairing - AI-agent support — the
.mdoutput andllms.txtwritten for models - Configuration —
services,sitemap,enableRobotsTXTand the rest
5 - Upgrade
To upgrade OINK, change the pinned module version. Then confirm that the site builds with reviewed diagnostics. Most content needs no changes. To convert 0.4 shortcodes to current native Markdown forms, use the migration tool. It starts with a dry run and avoids manual edits to hundreds of files.
An upgrade changes rendered output. Before you start, create an upgrade branch. You can discard that branch if you cancel the upgrade.
Maintained sites use Hugo Extended 0.168.0 and its built-in LibSass. No
external Sass installation is required. Do not enable --panicOnWarning or
HUGO_PANICONWARNING; Hugo’s built-in LibSass deprecation warning is
expected. Update Hugo workflow pins when upgrading; older-Hugo requirements
in the sections below describe those historical releases only.
Upgrade to 1.5.1
OINK v1.5.1 stabilizes the opt-in Duo View
introduced in 1.5.0 and corrects RSS, Print, navigation, validation, search, and
accessibility behavior. Sites that leave params.ui.compare unset build the exact
same pages and outputs as before. See the 1.5.1 release notes.
Verify public module resolution with replacements and workspaces disabled, pin
github.com/pgsty/[email protected], and build with --printPathWarnings. If you
enable params.ui.compare: true:
- Keep explicit
{#id}heading anchors aligned across translations so Sync Scroll can match sections accurately. - Set
languages.<lang>.params.ui.compare: falsefor any language that should neither display the reader nor appear as a target language. - Guard custom analytics snippets in
head-end.htmlwithwindow.OinkComparePaneso pane loads are not counted twice. Note that a local override of Hugo’sgoogle_analytics.htmlpartial is not used whencompareis enabled; see Analytics and SEO. - Allow same-origin frames (
frame-src 'self') in your Content Security Policy and make sure your server does not block same-origin framing withX-Frame-Options: DENYorframe-ancestors 'none'. - Open a translated Docs, Book, or blog page and verify that Open bilingual view loads the target language, syncs scrolling across shared headings, and switches cleanly on narrow screens.
Upgrade to 1.4.0
OINK v1.4.0 keeps the Hugo-only build boundary and adds local PlantUML,
unified diagram reading, richer local search, the opt-in table reader, and the
gallery blog layout. See the 1.4.0 release notes.
Verify public module resolution with replacements and workspaces disabled.
Pin github.com/pgsty/[email protected], build with --printPathWarnings, and review
navigation, image viewing, and reader settings. Source-copy consumers must also
refresh their fixed theme files; changing go.mod does not update a vendored copy.
OINK v1.3.1 repairs Markmap text contrast and fixed-TOC footer clearance, and
adds opt-in layouts for technical tables and long FileTree comments. Existing
content keeps its default appearance. Enable technical table layout
or FileTree wrap=true only where complete technical text is needed.
Keep preset: paper and the explicit [paper, slate, ink, terminal] menu when
the site offers all four styles. The 1.3.1 notes describe
these fixes and credit their contributor.
Read the release notes first
Keep params.plantuml: true or
plantuml.enable: true and remove svg_image_url to use the two bundled
browser scripts. No additional software or rendering service is required.
Keep a nonempty endpoint to retain server mode. To disable rendering entirely,
set params.plantuml: false or plantuml.enable: false; an empty endpoint now
selects local mode. Review
unsupported includes, libraries, and CSP requirements
before switching an existing diagram collection.
Each version’s release notes describe its changes, breaking changes, and upgrade steps. Before upgrading, read the target version’s notes:
- The release series in this site’s project blog
- The Releases page on GitHub
The notes identify required content changes, removed configuration keys, and changed default behavior. Read them to understand differences in the upgraded pages.
Upgrading the Hugo Module
For a production site, pin a published release tag or an explicitly selected
immutable commit. Do not follow a branch or use @latest. The example below
upgrades to the published v1.5.1 tag. Before you select a later tag, verify
that the release is published and its module resolves:
When selecting a tag, confirm that the module graph shows that exact version.
An explicitly selected immutable commit normally uses a Go pseudo-version
in go.mod. Commit the resulting go.mod and go.sum.
For the published tag in this example, go.mod contains:
make dev and make check set HUGO_MODULE_REPLACEMENTS for that command
only, using the sibling theme checkout. To verify a release tag, remove
environment replacements, disable GOWORK and HUGO_MODULE_WORKSPACE, and
check for persistent replace directives or _vendor/. See the
preview guide.
For a Git submodule, first confirm that it has no local edits. Fetch the tags. Check out the exact published version. Do not follow its remote branch:
Commit the updated submodule pointer after validation. For an offline archive
or clone, replace themes/oink/ with the selected version’s complete tree and
confirm that theme: still matches the directory name. The install-method
tradeoffs are in
From scratch and other install methods.
What to do after upgrading
These commands clear potentially stale caches, rebuild with the new version, and review the visible diagnostics.
--logLevel info includes informational diagnostics, while
Warnings remain visible. Review the deprecation messages
emitted by the pinned Hugo version before upgrading it; the severity and
removal schedule depend on the deprecated feature.
After the build passes, visually check the home page, a documentation page, a blog page, and the 404. Check both languages, both color schemes, the print view, and every site customization.
Upgrading from 1.0 to 1.1
No source migration was required from 1.0.0 to 1.1.0. Its Go 1.27.0 module directive was unchanged from 1.0.0. Validate current upgrades with Hugo Extended 0.168.0. Historical toolchain details remain in the 1.1 release note.
Review the affected surfaces before choosing the new pin:
Languages- All 32 interface catalogs have the same native-message schema. Check the site’s language labels, plural counts, and RTL direction. The site remains responsible for authored translations.
Taxonomies- Root pages become term-card directories with a taxonomy switcher. Review any taxonomy-template or CSS overrides, author portraits, and localized breadcrumbs.
Sidebars- Cached trees preserve effective page settings and remain usable without JavaScript. Test collapse, hover restore, mobile drawer, and keyboard focus. Hidden content must leave the focus order.
Groupssidebar_divider: trueretains a section’s children. Addbuild.render: neveronly if you intentionally omit the group’s own outputs. Verify child navigation, breadcrumbs, paging, Print, and Book contents.Root menus- Explicit
sidebar_root_menu: falsenow applies to self-root sections too. The current linkable root remains a location marker. Custom scripts- Feature-detect
OinkSidebarandOinkCommandPalette.registerSearchTailif an integration must also support 1.0.0. Restore branch state through the API rather than changing classes or ARIA attributes directly. 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:
These commands validate the local checkout. For release acceptance, pin the published version, build without a module replacement, then validate the deployed pages. The authoring and API details live in content groups, the sidebar contract, search actions, and image zoom.
Upgrading from 1.1 to 1.2
Paper is the default in OINK 1.2.0. Set params.ui.preset: slate before
adopting this change if the site must retain its existing appearance.
preset_menu: true enables reader choice; its default remains false.
Ink and Terminal require an explicit preset or menu list. Their buttons do
not carry experiment badges; the configuration opt-in remains unchanged.
Review custom dark brand selectors as described in Brand.
OINK 1.2.0 is available as a published tag. Apart from the default appearance change above, no content migration is required. Validate current upgrades with Hugo Extended 0.168.0, then verify the site:
- Check the chosen preset, light/dark icons, keyboard and mobile menus, saved preferences, and custom font/accent overrides. Sun means light; moon means dark. Switching styles must not change the saved light/dark preference.
- Recheck explicit navigation, hidden subtrees, page links, Blog pagination canonicals, and SEO alternates for pages without translations.
- Check CJK keyword-only search summaries and outline links with literal percent signs. Compare source-derived Edit, History, and Create child links on Windows or mounted content; mappings must yield repository-relative paths.
- Check Landing content with JavaScript disabled or blocked, preserved metric formatting, dialogs and keyboard shortcuts, copy fallback, Draw.io controls, and numbered equations at narrow widths.
- Run a production build for diagram endpoints and resource alt metadata;
malformed values now produce a warning and use a safe fallback. To disable
rendering intentionally, use
params.plantuml: falseorparams.drawio.enable: false. - Use the revised PDF and migration tools when testing publication or content conversion. Review PDF remote-resource opt-ins and migration diffs, including code examples nested in lists. The consumer-upgrade helper ships with 1.2.0 for inventory, module updates and exact-version validation.
The Architecture, Components, Shell, and Migration contracts describe the published 1.2.0 behavior.
The content migration toolkit
Several 0.4 shortcodes now use native Markdown forms. The theme repository ships a conversion tool that requires only the Python standard library:
Follow these four rules when you use the tool:
- A dry run is the default. Only
--writechanges files. Run the dry run, read the diff, and then write. - A second run should change nothing. If a second
--writereports changes, a transformation has not converged. Stop and inspect those files. - The tool leaves text inside fences unchanged. Documentation examples of old syntax therefore remain intact.
- If the tool cannot express a construct, it leaves that construct unchanged. It reports
file:lineand a reason for manual work. This is not a failure.
To convert one class first, use --only with the keys in the table’s last
column:
After conversion, rebuild, review warnings, and inspect the rendered pages. The tool guarantees correct syntax. You must verify the intended meaning.
The 0.4 → current syntax map
{{%/* alert color= title= */%}},{{%/* details */%}},{{%/* pageinfo */%}}, hand-written<details><summary>,callout{{</* tabpane */>}}+{{%/* tab header= */%}},{{</* code-group */>}}+{{</* code-tab */>}},tabs{{</* filetree */>}}withfiletree/folderandfiletree/file,filetree{{</* gallery */>}}withgallery/image,gallery{{</* echarts */>}},{{</* infographic */>}},datafencedoc-cards/doc-card,nav-cards/nav-card,card/cardpane,doc-carousel,cards{{</* imgproc */>}},{{</* image */>}},image{{</* readfile file= */>}},includeThe fence attribute,{filename="x"}fencetitle{{</* badge outline= */>}},badge{{</* example */>}}+ a fence,{{</* book-figures kind="tbl" */>}},eg{{%/* _param x */%}},iframe,conditional-text,blocks/*,netlify, a kindlessxref,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.
-
Pin the target version. Change
go.modto an OINK release tag, or use a complete versioned archive. During evaluation, an uncommittedgo.workcan point at a local checkout. -
Inventory the overrides. Classify each site-level file under
layouts/,assets/, andstatic/into four groups. Delete verified copies of the shared shell. Delete or mechanically rename components that OINK already provides. Retain brand customization in the smallest suitable hook. Keep business-specific data and interaction in the site. Delete files in reference order. Do not emptylayouts/at once. The home page or download page may still call a partial that you plan to remove. -
Move the configuration. Keep
title,languages.*,github_repo,github_branch,page_width, andparams.ui.*in their existing semantic positions. OINK adds no separate namespace. Enable search and the logo with these keys:hugo.ymlDocsy’s camelCase search keys have been renamed in OINK:
offlineSearch,offlineSearchIndex,offlineSearchMaxResults,offlineSearchOnServeandofflineSearchSummaryLengthall become their underscored forms. Rename them deliberately. The old migration registry stopped the build and named the replacement. That registry was removed. The theme now ignores an old key, so search remains off without a message. -
Fonts and styling compatibility. The Docsy Sass variables in
assets/scss/_variables_project.scssstill supply seed values for font roles. You do not need to delete them for an upgrade. Each of$td-fonts-serif,$font-family-sans-serif,$headings-font-family, and$font-family-codesupplies its role. The theme no longer reads Docsy’s Google Fonts switches$td-enable-google-fonts,$td-google-font-name, and$td-web-font-path. These unused switches cause no failure and have no effect. OINK bundles Inter, Chakra Petch, and IBM Plex Mono. Neither preset requests Google Fonts. To change fonts, use the token layer. See Brand and appearance. -
Convert the shortcodes. Docsy’s
alert,pageinfo,tabpaneandcardfamilies all have a current counterpart; convert them in bulk with the migration toolkit above, one--onlyclass at a time. -
Delete one group at a time. Build after each group. First test on a scratch copy. Record the theme commit, Hugo version, removed files, and generated HTML file count. After you confirm equivalent behavior, repeat the process on the production branch.
The “delete after verifying” class in step two is usually these files:
layouts/baseof.htmland the shared docs / blogbaseof*.html;- The navbar, footer, sidebar, TOC, search and head CSS partials and their hooks;
- The old brand documentation shell partials;
- Copies of the
asciinema,echarts,infographic,doc-carousel,details,tab/tabpane, card andparamshortcodes; - The JavaScript, Lunr copy, carousel code and SCSS that served only those implementations;
- PostCSS and Autoprefixer steps no site asset needs any more.
Two types of problem can appear after deletion.
A site script can report $ is not defined. OINK does not bundle jQuery,
which Docsy loaded in each page’s <head>. The theme does not need jQuery.
If your site needs it, load it in the site:
A home page that uses Docsy’s blocks/* fails an OINK build with
template for shortcode "blocks/cover" not found. OINK has no such shortcode
family. Use home page sections in data/home/<language>.yaml, or set
layout: landing on the page. See
Home and landing pages.
Upgrading from 0.4
0.4 changed several defaults. If an upgrade adds or removes a page feature, check these settings first:
-
Sequential paging is on by default.
docs,book, andblogpages have previous / next links at the page end. Documentation follows the sidebar tree. Blog pages follow time. For a page intentionally outside a sequence, setpager: false. -
The navbar appears on every layout. Its compact state has one row of icon navigation and no second mobile accordion menu. Remove local scripts and tests that depend on the old mobile menu. To disable the navbar for a section, set
navbar_enabled: falsein a cascade. -
The footer defaults to
fatfor the site. It accepts onlyfat/slim/none. Store footer data indata/footer/<language>.yaml, ordata/footer.yamlfor a single-language site. A remainingfooterkey indata/homeproduces a warning with the new location. -
Single-key navigation is on by default.
/opens full search, and\opens command-only mode. Update training material that describes the old behavior. Page actions now use a split button beside the breadcrumbs. -
The code block DOM changed. A
.td-codewrapper now encloses the original.highlight. Both.highlightand.chromaremain. In site CSS, replace a direct child selector such as.td-content > .highlightwith the descendant selector.td-content .highlight. -
Two ICP footer parameters were removed. The keys
footer_icpandfooter_icp_urlbecame one string that accepts inline Markdown.hugo.yml -
For mathematics, enable passthrough in the site. Hugo does not merge a theme’s
markupconfiguration. If the site uses\(…\),\[…\], or$$…$$, enable Goldmark passthrough in its ownhugo.yml. See Math.
The complete configuration for all of these is in Configuration and Layouts and page types.
Verify
After “the build passed”, the upgrade still requires checks. Inspect each surface:
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:
Another site runs the equivalent build, link, output and browser checks; the details are in Troubleshooting.
Complete the final checks in the real environment. Deploy a preview. Verify its pages and browser network requests at the real URL. After review, merge the upgrade and run a production smoke test.
Rollback
To roll back the theme, restore the version pin:
Three principles:
- Keep the pre-upgrade module pin, the site commit and the known-good deployment artifact, and restore all three together.
- Do not perform a partial rollback. Old layout copies over a new theme produce a mixed implementation. This is harder to diagnose than either complete version.
- Keep the upgrade branch and its acceptance evidence. A rollback first restores production. It does not discard completed upgrade work.
Rolling back the deployed output itself (republishing the previous deployment) is in Deploy.
Related
- Deploy — rolling back deployed output
- Troubleshooting — reading a build error after an upgrade
- Local preview — clearing caches and the
go.workworkspace - From scratch and other install methods — weighing the four install methods
- Components — each component’s current form
6 - Troubleshooting
If a problem occurs, first run a clean production build. Read the first error. Later errors usually result from it:
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:
The two most common shortcode errors look like this. Each ends with
file:line:column:
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 |
Search
| 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,- Duplicate output paths, invalid parameters, incomplete external integrations
Output trust check,- Checks every
href/srcin all four outputs for site-relative paths orhttp(s)/mailto/tel. Rejectsjavascript:URLs and inlineon*handlers. A cross-site<iframe>,<script>, or<img>requires explicit--third-party Translation parity,- Checks that each English page has a Chinese counterpart and that rendered heading IDs match. Detects misaligned anchors
The full gate,- 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 andllms.txtoutput 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 intests/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 ingo.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 repositoryIt 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/andresources/_genand 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.
- Theme and documentation issues: https://github.com/pgsty/oink/issues
- Issues with this site’s content: https://github.com/pgsty/oink.pgsty.com/issues
- Upstream Docsy compatibility discussion: https://github.com/google/docsy/discussions
Related
- 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