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