Skip to content

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