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