Inspect Hugo File Mounts Before You Change a Site

Add a mount to a Hugo site and you can quietly lose a chunk of content: hugo config mounts shows you the file map before that happens. It prints the directories and files Hugo exposes through its unified file system, which makes a mount change easy to review before you build. Allow about ten minutes.

You need a Hugo project and a shell. The inspection commands are read-only and do not need elevated privileges. This guide targets Hugo 0.123.7, the version installed on the reference machine: mount output and available flags can differ between releases, so check the installed binary before copying an example into automation.

1. Confirm the installed command

Run the version and help checks from the project directory. These commands only report information:

$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2026-03-17T19:51:14Z VendorInfo=ubuntu:0.123.7-1ubuntu0.3+esm2
$ hugo config mounts --help
Print the configured file mounts

Usage:
  hugo config mounts [flags] [args]

The subcommand is hugo config mounts. It is not a build command and does not write generated pages. The installed manual documents four command-specific options: --baseURL, --cacheDir, --contentDir and --theme. It also accepts global configuration options such as --config and --source.

2. Print the project's effective mounts

From the directory containing the project configuration, run:

$ hugo config mounts

Hugo prints JSON describing the module or project path, then a mounts array. Each entry has a source and a target: the source is the path Hugo reads from, the target is where that material appears in Hugo's unified file system, such as content, layouts or assets.

A minimal project with no custom mount configuration normally shows entries similar to these:

{
   "path": "project",
   "mounts": [
      { "source": "content", "target": "content" },
      { "source": "data", "target": "data" },
      { "source": "layouts", "target": "layouts" },
      { "source": "i18n", "target": "i18n" },
      { "source": "archetypes", "target": "archetypes" },
      { "source": "assets", "target": "assets" },
      { "source": "static", "target": "static" }
   ]
}

The output also includes fields such as version, time, owner and dir, describing the module being reported. Do not treat the complete JSON as a fixed template: the useful part for this task is the effective mount list.

3. Check a custom mount without building

Hugo mounts are configured under module.mounts. This example keeps the project's normal content directory and exposes a sibling directory below content/shared:

module:
  mounts:
    - source: content
      target: content
    - source: ../shared-content
      target: content/shared

Run the inspection again after saving the configuration:

$ hugo config mounts
...
{ "source": "content", "target": "content" },
{ "source": "../shared-content", "target": "content/shared" }
...

A mount is a path mapping, not a copy operation. Hugo reads the source through the target path while processing the site. The command does not create content/shared on disk, and it does not move or delete the sibling directory.

4. Watch the default-mount trap

Adding a mount for a component changes how that component is assembled. Hugo's module documentation says that defining a mount for a component in project configuration removes that component's default mount. If you still need the default directory, include it explicitly, as the example above does for content.

This is the most useful reason to run the inspection before a build. Add a custom content mount but leave out the ordinary content entry, and pages in the original directory can disappear from the unified file system: the build then appears to succeed while publishing fewer pages.

Do not mix this configuration casually with the legacy directory settings archetypeDir, assetDir, contentDir, dataDir, i18nDir, layoutDir or staticDir. The upstream module documentation recommends mounts instead when you are defining explicit source-to-target mappings. Keep one clear source of truth for each component.

5. Inspect a different project or configuration

When the current working directory is not the project root, pass its path with --source:

$ hugo config mounts --source /path/to/site

Replace the placeholder with an existing project directory. The command looks for the normal Hugo configuration names there. If the project uses a specific configuration file or configuration directory, use the installed command's global --config or --configDir options and verify the result:

$ hugo config mounts --source /path/to/site --config hugo.yaml
$ printf 'exit status: %s\n' "$?"
exit status: 0

Do not use --source to test an arbitrary directory and then assume it represents the real site. A missing configuration can produce default-looking mounts, which may hide a project-specific mount file. Check the reported dir and the paths in the output before drawing conclusions.

6. Investigate a surprising result safely

If a source is missing, first inspect the configuration files and filesystem paths without changing them:

$ pwd
$ find . -maxdepth 2 -type f \( -name 'hugo.yaml' -o -name 'hugo.toml' -o -name 'hugo.json' \) -print
$ ls -ld content ../shared-content
$ hugo config mounts

Check spelling, relative-path bases and the target component name. Relative sources are interpreted in the context of the module or project that declares them, so a path that looks correct in a copied configuration may point somewhere else in its real location.