Regenerate Hugo CLI Markdown Documentation Safely

You will finish with a fresh directory of Markdown pages documenting the Hugo command-line interface, generated from the Hugo binary installed on your Linux machine. The examples match Hugo 0.123.7, the version checked for this guide. Allow about ten minutes for a first run, plus time to review the files before copying them into a documentation project.

You need the hugo command and a writable destination. This command generates documentation files. It does not build your site, publish anything or require elevated privileges. Do not use sudo merely because the output is documentation. If the destination belongs to another user or is inside a protected system directory, fix the directory ownership or permissions through your normal administration process instead of hiding the problem with a blind root command.

1. Check the installed Hugo contract

Start by confirming which binary will run and which version supplies the command. These are ordinary, read-only checks:

$ 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 doc --help
Generate Markdown documentation for the Hugo CLI.
...
      --dir string   the directory to write the doc. (default "/tmp/hugodoc/")

The exact build date and vendor text will vary. The useful checks are that hugo resolves to the binary you intend to use and that its help names gen doc with a --dir destination option.

2. Choose an isolated output directory

hugo gen doc writes one Markdown file per command. Its default directory is /tmp/hugodoc/, but an explicit directory makes the destination visible in a script and prevents you from forgetting where the result went. Create a new scratch directory outside your Hugo project:

$ output_dir=$(mktemp -d /tmp/hugo-cli-docs-XXXXXX)
$ printf 'output directory: %s\n' "$output_dir"
output directory: /tmp/hugo-cli-docs-a1B2c3

The suffix is generated and will differ. Keep the shell variable in the same shell session. If you close the terminal, use the full printed path in later commands. The directory is ordinary temporary data, so it is not a suitable long-term documentation location.

There is no need to set --config, --source or --destination for this job. They are inherited global Hugo options, but the command's own output control is --dir. Adding unrelated project options makes it harder to see whether you generated CLI documentation or accidentally started configuring a site build.

3. Generate the Markdown files

Run the generator with the scratch path:

$ hugo gen doc --dir "$output_dir"
Generating Hugo command-line documentation in /tmp/hugo-cli-docs-a1B2c3/ ...
Done.

Successful completion is reported with Done. on this installed build. Hugo creates files such as hugo.md, hugo_gen.md and hugo_gen_doc.md, along with pages for the other commands exposed by that binary. The set is version-dependent: a different Hugo release or build can expose different commands and flags.

Check that the directory contains files and that the command-specific page has the expected front matter and synopsis:

$ find "$output_dir" -maxdepth 1 -type f | sort | head
/tmp/hugo-cli-docs-a1B2c3/hugo.md
/tmp/hugo-cli-docs-a1B2c3/hugo_completion.md
/tmp/hugo-cli-docs-a1B2c3/hugo_config.md
...
$ sed -n '1,45p' "$output_dir/hugo_gen_doc.md"
---
title: "hugo gen doc"
slug: hugo_gen_doc
url: /commands/hugo_gen_doc/
---
## hugo gen doc
...
hugo gen doc [flags] [args]

Your sorted list and the generated text should be treated as the source of truth for the installed version. Do not copy an option from an online page into local documentation without checking that it appears in the generated file or in hugo gen doc --help.

4. Review before replacing project documentation

Generation is separate from integration. First count and inspect the output without touching the Hugo project:

$ find "$output_dir" -maxdepth 1 -type f -name '*.md' | wc -l
42
$ grep -n -E '^(title|slug|url):' "$output_dir/hugo_gen_doc.md"
2:title: "hugo gen doc"
3:slug: hugo_gen_doc
4:url: /commands/hugo_gen_doc/

The count of 42 is what this Hugo 0.123.7 installation produced in a clean directory; it is an observation, not a promise for every release. More useful than a count is a review of the changed files and their front matter. The generated pages use Markdown with Hugo-style front matter, so they can be copied into a documentation content directory that expects that format.

5. Compare with an existing documentation tree

If your project keeps generated command pages in docs/content/en/commands, compare the scratch output before copying anything:

$ diff -ru -- "docs/content/en/commands" "$output_dir" | less

Replace the left-hand path with the real directory in your project. This is a read-only comparison. Look for expected version changes, removed commands, changed defaults and altered inherited flags. A large diff may be correct after a Hugo upgrade, but it deserves review rather than an automatic overwrite.

Keep locally maintained pages separate when possible. The generator creates command pages from the CLI; it is not a general documentation migration tool and does not know which extra pages your project has added. The official Hugo documentation workflow uses the generated command output as an input to the documentation tree, so preserve any project-specific files that are not regenerated.

6. Handle failures without escalating privileges

A non-zero exit status usually means the destination or the Hugo environment needs investigation. Capture the command and status, then inspect the path:

$ hugo gen doc --dir "$output_dir"
$ status=$?
$ printf 'hugo gen doc status: %s\n' "$status"
$ test -d "$output_dir" && ls -ld "$output_dir"
hugo gen doc status: 0

For a real failure, retain the non-zero status instead of printing a misleading success message. Check that the destination is writable with test -w, that the filesystem has space, and that the Hugo binary is still the expected version. If you used a path inside a project, check whether another process is changing it. These checks are safer than rerunning with sudo, which can leave root-owned files behind and make later ordinary runs fail.

If the generated set is incomplete, return to step 1 and inspect hugo version and hugo gen doc --help. Hugo command pages describe the command registered by the binary that ran; they cannot document commands that are absent from that build.

7. Clean up the scratch output

Once the review is complete, remove only the temporary directory you created. This is destructive, so verify the variable before running the command:

$ printf 'will remove: %s\n' "$output_dir"
will remove: /tmp/hugo-cli-docs-a1B2c3
$ case "$output_dir" in
  /tmp/hugo-cli-docs-*) rm -rf -- "$output_dir" ;;
  *) printf 'refusing unexpected path: %s\n' "$output_dir" >&2; exit 1 ;;
esac
$ test ! -e "$output_dir" && echo 'scratch output removed'
scratch output removed

If you need to investigate a failed run, keep the directory instead and record its path. There is no undo for rm -rf, but the scratch output can always be regenerated from the same Hugo version. Do not use this cleanup pattern with a project path or a variable whose value you have not inspected.