Deployment

Ship the built site to any static host.

On this page

pnpm build produces a self-contained public/ directory. Anything that serves static files can host it — the only platform-specific part is telling the host how to run the build.

Build settings

Setting	Value
Build command	`pnpm build`
Output directory	`public`
Node version	`22.13` or newer

Set baseURL in hugo.toml to the final URL before deploying — canonical links, the sitemap and the RSS feed all depend on it.

If you enabled showLastModified, the build also needs the full git history — fetch-depth: 0 for actions/checkout, or the platform's equivalent. A shallow clone builds green and stamps every page with the same date, because the one commit it fetched is the only date Hugo can see.

Platforms

Tartarus ships a working workflow at .github/workflows/deploy.yml — enable Pages with Source: GitHub Actions and push. The two lines that are easy to get wrong:

yaml

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # only if showLastModified is on
      - run: pnpm build           # not `hugo` — Pagefind runs in this step

text

Build command:       pnpm build
Build output:        public
Environment:         NODE_VERSION = 22

Add HUGO_VERSION as an environment variable to pin the Hugo release.

toml

# netlify.toml
[build]
  command = "pnpm build"
  publish = "public"

[build.environment]
  NODE_VERSION = "22"
  HUGO_VERSION = "0.146.0"

json

{
  "buildCommand": "pnpm build",
  "outputDirectory": "public",
  "framework": null
}

Install Hugo in the build step, or use the Hugo preset and override the build command so Pagefind still runs.

Serving from a subdirectory

If the site is not at the root of a domain, set the full path:

toml

baseURL = "https://acme.github.io/docs/"

Hugo rewrites internal links, and two attributes on <html> carry the rest: data-pagefind points at the index, and data-baseurl is handed to Pagefind as its baseUrl.

The second one matters more than it looks. Pagefind indexes the built output, so the URLs it stores are relative to the site root — /docs/guides/deploy/, with no knowledge of the subdirectory. Without baseUrl, every search result on a project Pages site is a 404, while the pages themselves load fine.

Do not skip the Pagefind step

Deploying with hugo alone produces a site whose search box opens and finds nothing. The build command must be pnpm build, which runs Hugo and Pagefind.

Edit this page