Configure the Same Theme Directory Across Multiple Hugo Sites (themesDir)

When creating multiple Hugo sites and a shared theme on a local PC, you can develop them while referencing the same theme directory.
Tags:

The ways to make multiple Hugo projects reference the same theme are as follows.

  1. Create a theme repository on GitHub or elsewhere, and clone that repository into multiple Hugo projects.
  2. Replace each Hugo project’s themes directory with a symbolic link to a shared theme directory.
  3. Configure the settings file (config.toml) to reference the shared theme directory.

The first method is the most common, but when applying the same theme to each site with Git, it can be a little cumbersome during development. In that case, the second and third methods are recommended.

On operating systems such as Linux and macOS where symbolic links can be created, it is easy to reference a shared theme directory with a symbolic link. For example, assume there is a shared theme directory (hugo_themes) and three Hugo projects that reference it (site1, site2, and site3) as follows.

.
├── hugo_themes (shared theme directory)
│   └── mytheme
│       ├── archetypes
│       ├── layouts
│       ├── static
│       └── ...
├── site1  (Hugo site 1)
├── site2  (Hugo site 2)
└── site3  (Hugo site 3)

If you replace each Hugo project’s themes directory with a symbolic link to hugo_themes, all sites can point to the same theme directory.

$ cd site1
$ rmdir themes
$ ln -s ../hugo_themes themes

Because setting the theme name to use is still required, set the theme name in each Hugo project’s configuration file (config.toml). site1/config.toml

theme = "mytheme"

Configure a Shared Theme Directory in the Settings File

You can also configure the shared theme directory in Hugo’s configuration file (config.toml). The theme directory is configured with a variable called themesDir, and this directory path can be set to a path above the Hugo project directory.
config.toml

themesDir = "../hugo_themes"
theme = "mytheme"

For example, if each Hugo project’s configuration file is set as above, the shared theme directory (hugo_themes/mytheme/) in the parent directory can be used.

Without using the configuration file, you can also specify the theme directory with the Hugo command option --themesDir.

$ hugo server --themesDir ~/gitwork/hugo_themes

If both the themesDir variable in the settings file and the command-line argument --themesDir are specified, the command-line argument takes precedence.