Hugo Content Checks Before Publishing

A Hugo build can succeed while publishing the wrong content. Drafts may be included by the selected build mode, files from an earlier build may remain in the output directory, and example content from a theme may appear beside the site’s real pages. A useful pre-publish gate tests those predictable conditions explicitly; it does not treat a green build as proof that the site is ready.

The practical boundary is simple: automate conditions that can be stated as invariants, then review the rendered site and editorial substance separately.

Define the publication invariants

Before writing a script, describe what must be true when publication is allowed. A small Hugo site might use these conditions:

• The generated output starts from a clean destination.
• The production build uses the intended draft and date behavior.
• No draft content is present in the publishable output.
• Known theme-demo markers or example paths are absent.
• The build exits successfully and produces the expected output directory.

These are not a complete quality standard. They are bounded failure conditions. Each one should produce a message that names the violated condition and, when possible, the affected file.

That distinction matters because “the build passed” describes a process result, not a publication decision. A successful build can still satisfy the wrong configuration.

Start with a clean output directory

A verification build should not inspect an output directory that contains files from an earlier run. One practitioner guide recommends removing public before a verification build because stale generated files can otherwise remain available for inspection (the clean-output recommendation).

A deliberately narrow shell step might look like this:

set -eu

rm -rf public
hugo --environment production

Treat this as a hypothetical implementation pattern, not a universal deployment command. The cleanup target must be the generated destination, never a directory containing source content, deployment state, or other material that the repository needs. If the deployment system owns the output directory, use its documented clean-build mechanism instead of deleting files blindly.

After the build, add checks for expected output. For example, a site can fail when the destination is missing, empty, or lacks a known production entry point. The exact expectations depend on the site’s structure; the important part is that they are written down rather than inferred from a visual glance.

Make draft handling explicit

Draft status belongs in the gate because it is a publication decision, not merely a writing preference. A practitioner workflow describes checking draft status in both local and CI workflows to prevent accidental publication (the draft-status checker pattern).

The check should inspect the content source and report the path of every disallowed draft. It should also make the production build mode explicit. Another practitioner guide explains that Hugo’s draft behavior is affected by the build options used, so a workflow should test the intended configuration instead of relying on an assumed default (the explanation of Hugo draft behavior).

A useful failure message is more specific than draft check failed:

Publication blocked: draft content found
- content/notes/revise-pricing.md
- content/posts/example.md

Decide separately how the gate should handle future-dated or expired content. The available guidance does not establish a complete rule for those cases, and the correct behavior can depend on the site’s editorial and build conventions. Do not quietly treat a draft check as a complete date-policy check.

Inspect generated output for known unwanted content

Source checks and output checks catch different problems. A source directory may look reasonable while a theme’s example content, copied assets, or an unexpected section is still rendered. A Hugo workflow note specifically warns about theme demo content leaking into generated output (the theme-content warning).

For a site with a known marker, a targeted check can search the generated files:

if grep -R -n -E 'Theme Demo|Example Post|replace-this-marker' public; then
  echo "Publication blocked: known demo content found in public/"
  exit 1
fi

This is a hypothetical example. Replace the markers with strings or paths that are genuinely inappropriate for the site. Keep the list small and review it when legitimate copy changes; otherwise, the check can become noisy. A marker search also cannot discover every unintended page, so it should supplement—not replace—a review of the generated page list and selected rendered pages.

Run one gate locally and in CI

The same command should be available to a maintainer before deployment and to CI after a change is pushed. Local execution keeps feedback close to the edit. CI supplies a shared enforcement point and a reproducible environment, provided the Hugo version, theme, dependencies, and configuration are controlled consistently.

Keep the gate’s output actionable. Report the invariant, the file or path involved, and the next corrective action. Avoid a script that only returns a nonzero status with no explanation; it forces maintainers to repeat the investigation manually.

Leave rendered and editorial review outside the gate

Deterministic checks can establish that certain files, statuses, and markers meet declared rules. They cannot establish that a page reads correctly, that navigation works as intended across viewports, that a template presents content well, or that a factual claim is accurate. Those questions need rendered inspection and editorial judgment. A separate Hugo content preview workflow can provide that review boundary.

The result is not a claim that automation makes publication safe. It is a clearer sequence: clean the generated destination, build with explicit production settings, fail on known source and output violations, then inspect what the reader will actually see. The narrower the invariant, the easier it is to trust the failure and maintain the check.