Inspect Hugo File Mounts Before You Change a Site

You will finish with a reliable way to see which directories and files Hugo exposes through its unified file system. That makes a mount change easier to review before a build, especially when content or assets live outside the usual project directories. Allow about ten minutes. You need a Hugo project and a shell; the inspection commands are read-only and do not require 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. Their values describe the module being reported. Do not compare 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" }
...

Use the real JSON output as the checkpoint, not the shortened display above. Confirm that every intended source appears and that every target is the path your templates and content references expect.

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 does for content.

This is the most useful reason to run the inspection before a build. If you add a custom content mount but omit the ordinary content entry, pages in the original directory may disappear from the unified file system. The build can then appear 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 will look 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 as a way 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.

If you are about to edit a production site's configuration, make a version-control checkpoint first. A configuration edit can change which content is published, even though hugo config mounts itself is harmless. Recovery is to restore the previous configuration from version control or your normal backup, then rerun the inspection and a build. Do not use sudo to inspect or edit a project unless the project permissions genuinely require it.