Generate a Reproducible Hugo Man Page Set

You will finish with a complete set of man pages for the installed Hugo CLI, written to a directory you choose and checked without touching your project files. The examples use Hugo 0.123.7, the version installed on this machine.

Allow about ten minutes. You need a shell and the hugo executable. The command does not need sudo. It can create directories and write files, so choose the destination deliberately before running it. If the destination already contains generated man pages, treat the run as an overwrite operation and make a backup first.

1. Confirm the installed command

Check which executable will run and record its version. This is read-only and should be an ordinary user command:

$ command -v hugo
/usr/bin/hugo
$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2026-03-17T19:51:14Z VendorInfo=ubuntu:0.123.7-1ubuntu0.3+esm2

The exact build date and vendor suffix can differ on another host. The version matters because the generated pages describe the CLI available from that binary, not necessarily the Hugo release you use elsewhere.

Checkpoint: if command -v hugo finds nothing, stop here and install or select Hugo through your normal software-management process. Do not continue with a different binary by accident.

2. Inspect the command before writing anything

Ask Hugo for the command help. This confirms the option spelling and shows the default destination:

$ hugo gen man --help
Generate man pages for the Hugo CLI

Usage:
  hugo gen man [flags] [args]

Flags:
      --dir string   the directory to write the man pages. (default "man/")
  -h, --help         help for man

The inherited Hugo options shown by this help are not extra output controls for the man-page generator. The option that selects the output directory is --dir. With no option, Hugo writes below a directory named man in the current working directory.

3. Choose and protect the destination

Use a directory dedicated to generated documentation. This example keeps the output in a build area under the current project:

$ mkdir -p build
$ test ! -e build/man || cp -a build/man "build/man.backup.$(date +%Y%m%d%H%M%S)"
$ find build -maxdepth 1 -type d -printf '%f\n' | sort
build

The copy is only needed when build/man already exists. It preserves the old directory so you can compare or restore it. If the files are tracked by Git, an ordinary commit or a saved patch is another suitable recovery point.

Warning: hugo gen man is a file-writing command. Do not point it at a directory containing hand-written man pages or unrelated files unless you have checked the names it may replace.

4. Generate the man pages

Run the generator with an explicit destination:

$ hugo gen man --dir ./build/man
Directory build/man/ does not exist, creating...
Generating Hugo man pages in build/man/ ...
Done.

Hugo creates the destination when it does not exist. The generated files use section 1 names such as hugo.1, hugo-gen.1 and hugo-gen-man.1. The complete set also includes pages for other commands and shell completion variants exposed by this Hugo build.

Checkpoint: a successful Done. message means the generator completed its write operation. It does not by itself prove that the directory contains the page you expected, so inspect it next.

5. Verify the output and read one page

Count the section 1 files, list the names, and inspect the page for the command you ran:

$ find build/man -maxdepth 1 -type f -name '*.1' | sort | wc -l
42
$ find build/man -maxdepth 1 -type f -name '*.1' -printf '%f\n' | sort | grep -E '^(hugo|hugo-gen-man)\.1$'
hugo.1
hugo-gen-man.1
$ man -l build/man/hugo-gen-man.1 | col -b | sed -n '1,28p'
HUGO-GEN-MAN(1)                 Hugo Manual                 HUGO-GEN-MAN(1)

NAME
       hugo-gen-man - Generate man pages for the Hugo CLI

The count is an observation from Hugo 0.123.7 on this host, not a stable promise for every release or build. A different count is normal when the command set changes. The useful checks are that the directory contains files, the expected command page exists, and the page identifies itself as hugo-gen-man.

If man -l is unavailable, inspect the generated source directly:

$ sed -n '1,24p' build/man/hugo-gen-man.1
.nh
.TH "HUGO-GEN-MAN" "1"
...
.SH NAME
...

The exact date and later roff lines vary. Do not edit the generated file to add local prose: regenerate it from the Hugo binary when the CLI changes.

6. Install the pages only when you need system-wide access

Keeping the files in the project or build directory is usually enough for packaging, review or a documentation artefact. To make them visible through the system man database, use the installation method required by your operating system and package policy. That step needs elevated privileges and is deliberately not part of the generation command.

For a temporary local check, keep using man -l build/man/hugo-gen-man.1. It avoids copying files into /usr/share/man and avoids changing the host's system documentation. If you later install a page and need to undo it, remove only the files you installed, or use the package manager's recorded uninstall path. Do not delete an entire system man directory.

7. Re-run after a Hugo upgrade

Generate into a fresh versioned directory when comparing releases:

$ new_dir="build/man-$(hugo version | awk '{print $2}' | tr -cd '[:alnum:].-')"
$ hugo gen man --dir "$new_dir"
$ find "$new_dir" -maxdepth 1 -type f -name '*.1' | sort | wc -l
42

The shell variable is only a destination name derived from the local version output. Review it before using the directory in a script. Comparing versioned trees makes CLI additions and removed commands visible without overwriting the previous result. Once you have recorded the comparison, remove an obsolete build directory only if it contains no other files and you no longer need its recovery copy.