Generate Hugo's Docs, Man Pages and Chroma CSS

You want Hugo's own command docs, man pages or a highlighter stylesheet, and hugo gen builds all three without touching your project. It covers hugo gen doc, hugo gen man and hugo gen chromastyles, writing everything to a directory you choose. Give it 10 to 15 minutes for a first run, including a look at what came out. None of it needs root privileges when you write somewhere you already own.

1. Check the installed command and version

The installed manual is for hugo-gen(1), but the executable is hugo. Use the parent command followed by the gen subcommand; a standalone hugo-gen binary does not exist.

$ 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
$ hugo gen --help
A collection of several useful generators.

Your build date or vendor text can differ. The version matters because the generated documentation and available flags follow the installed Hugo build. If command -v hugo finds nothing, install Hugo through your normal package or release process before continuing; do not reach for sudo just to inspect a command.

2. Generate Markdown CLI documentation in a scratch directory

hugo gen doc creates one Markdown file per Hugo command, with front matter suitable for rendering in Hugo. Its one option is --dir; the default is /tmp/hugodoc/. Pick an explicit directory when you are reviewing output, so the destination is obvious and repeatable.

$ work=$(mktemp -d -p /tmp hugo-gen-)
$ hugo gen doc --dir "$work/doc"
Directory /tmp/hugo-gen-abc123/doc/ does not exist, creating...
Generating Hugo command-line documentation in /tmp/hugo-gen-abc123/doc/ ...
Done.
$ find "$work/doc" -maxdepth 1 -type f -name '*.md' -printf '%f\n' | sort | head
hugo.md
hugo_completion.md
hugo_completion_bash.md
hugo_completion_fish.md
hugo_completion_powershell.md
hugo_completion_zsh.md
hugo_config.md
hugo_config_mounts.md
hugo_convert.md
hugo_convert_toJSON.md

The random suffix comes from mktemp, so your path will differ. The command creates the destination if it needs to. It writes documentation for the Hugo CLI itself, not a site build and not a single page for your current project.

Review the result before copying anything into a content tree:

$ sed -n '1,24p' "$work/doc/hugo_gen.md"
$ test -s "$work/doc/hugo_gen.md" && echo 'documentation file is non-empty'
documentation file is non-empty

If you do not need the scratch output, remove only the directory named by $work after checking it; that deletion is irreversible. Keeping it until you have compared the files is the safer default.

3. Generate man pages with an explicit destination

hugo gen man generates man pages for Hugo's CLI. Its default destination is a man/ directory under the current directory, an easy way to drop generated files into the wrong repository. Pass --dir every time while experimenting.

$ hugo gen man --dir "$work/man"
Directory /tmp/hugo-gen-abc123/man/ does not exist, creating...
Generating Hugo man pages in /tmp/hugo-gen-abc123/man/ ...
Done.
$ find "$work/man" -maxdepth 1 -type f -name '*.1' -printf '%f\n' | sort | head
hugo-completion-bash.1
hugo-completion-fish.1
hugo-completion-powershell.1
hugo-completion-zsh.1
hugo-completion.1
hugo-config-mounts.1
hugo-config.1
hugo-convert-toJSON.1

Check that the generated file is plain man-source text before installing or packaging it:

$ sed -n '1,18p' "$work/man/hugo-gen.1"
.nh
.TH "HUGO-GEN" "1"
...
$ test -s "$work/man/hugo-gen.1" && echo 'man page is non-empty'
man page is non-empty

4. Generate Chroma CSS to standard output

hugo gen chromastyles prints CSS for the Chroma code highlighter. The default style is friendly. Use --style to pick another, then redirect standard output to a new file. This verified example uses github and keeps the file in the same scratch directory.

$ hugo gen chromastyles --style=github > "$work/github.css"
$ wc -c "$work/github.css"
5232 /tmp/hugo-gen-abc123/github.css
$ sed -n '1,4p' "$work/github.css"
/* Background */ .bg { background-color: #ffffff; }
/* PreWrapper */ .chroma { background-color: #ffffff; }
/* Other */ .chroma .x {  }
/* Error */ .chroma .err { color: #a61717; background-color: #e3d2d2 }

The byte count and colour values depend on the installed Hugo and Chroma versions, so treat them as a shape check rather than a promise. What actually matters is a clean exit, a non-empty file and selectors such as .chroma. Redirecting with > into an existing file truncates it before Hugo even runs, so pick a new name first or write to a temporary file and swap it in after review.

The command's help says this stylesheet is needed when markup.highlight.noClasses is disabled, which is a site configuration decision, not a reason to generate CSS for every Hugo project. If your site already uses inline highlighting or another stylesheet, keep the generated file separate until you have checked the setting.

5. Keep global flags in their proper place

gen inherits global Hugo flags such as --config, --configDir, --source, --destination, --environment, --quiet, --verbose and --logLevel. The subcommands also have their own --dir option where documented. Do not confuse the generator's output directory with Hugo's general site destination.

For a project-specific documentation run, check the exact option set first:

$ hugo gen doc --help
Generate Markdown documentation for the Hugo CLI.
...
      --dir string   the directory to write the doc. (default "/tmp/hugodoc/")
$ hugo gen man --help
This command automatically generates up-to-date man pages of Hugo's
command-line interface.
...
      --dir string   the directory to write the man pages. (default "man/")

Reach for --config or the other inherited flags only when you actually need to control the Hugo project context. If a generator fails, rerun with --verbose or --logLevel debug for diagnostics, but do not assume debug output means nothing was written; check the destination and its timestamps after any failed or interrupted run.

6. Review and promote output deliberately

Generation is not installation. Before moving anything into a repository, diff it against the version already tracked there:

$ diff -u /path/to/old/hugo-gen.1 "$work/man/hugo-gen.1"
$ git -C /path/to/your-hugo-site status --short
$ git -C /path/to/your-hugo-site diff --check

Swap the placeholder paths for a real repository you own. The last two commands are read-only, but the status they report can still surface unrelated changes; stop if the destination holds work you did not expect. Do not run git add, commit, copy or install commands until you have confirmed the intended files and read their contents.