Generate a Reproducible Hugo Man Page Set

You need real man pages for the Hugo CLI without touching /usr/share/man, and hugo gen man writes a full set to any directory you choose. This walks through generating them, checking one, and keeping them separate from 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 creates directories and writes files, so choose the destination deliberately before running it. If the destination already holds generated man pages, treat the run as an overwrite and take 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.

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 this help lists are not extra output controls for the man-page generator. The one that selects the output directory is --dir. Leave it out and 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 only fires when build/man already exists. It keeps the old directory around so you can compare or restore it. If the files are tracked in Git, an ordinary commit or a saved patch works just as well as a recovery point.

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 if it does not exist. The generated files use section 1 names such as hugo.1, hugo-gen.1 and hugo-gen-man.1. The full set also covers other commands and shell completion variants exposed by this build.

5. Verify the output and read one page

Count the section 1 files, list the names, and read the page for the command you just 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

42 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 once the command set changes. The checks that actually matter are that the directory holds files, the expected command page exists, and the page identifies itself as hugo-gen-man.

If man -l is not available, read 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 hand-edit the generated file to add local prose; regenerate it from the Hugo binary whenever the CLI changes instead.

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 whatever installation method your operating system and package policy requires; that step needs elevated privileges and is deliberately not part of the generation command.

For a quick local check, keep using man -l build/man/hugo-gen-man.1. It avoids copying files into /usr/share/man and avoids touching the host's system documentation at all. If you do later install a page and need to undo it, remove only the files you installed, or use the package manager's recorded uninstall path; never 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 local version output; check it before using the directory in a script. Comparing versioned trees makes CLI additions and removed commands visible without overwriting the previous result. Once the comparison is recorded, remove an obsolete build directory only if it holds nothing else and you no longer need its recovery copy.