Configuration Structure

This article will try to briefly introduce Hugo’s configuration structure.

Configuration Formats

Although Hugo supports TOML, YAML and JSON, I recommend using TOML or YAML, as JSON does not support annotations/comments.

Configuration Filenames

Since Hugo 0.110.0, Hugo will prefer to use the hugo.* configuration file, although config.* still works, but I recommend using hugo.* to distinguish it from the configuration of other projects.

Single Configuration File

The single configuration file is hugo.* in the project root directory.

Hugo can also specify multiple configuration files with the -config parameter: hugo --config a.toml,b.toml,c.toml.

Configuration Directory

Although the single configuration file is simple and convenient, it also has the obvious disadvantage that it is difficult to read once there are too many configurations, which is even worse in the case of multiple environments and multilingual mode, and the configuration directory can better cope with this situation.

 1tree config
 3├── _default
 4│   ├── hugo.toml
 5│   ├── languages.toml
 6│   ├── menus.en.toml
 7│   ├── menus.zh-hans.toml
 8│   └── params.toml
 9│   └── params.en.toml
10│   └── params.zh-hans.toml
11├── development
12│   ├── hugo.toml
13│   └── params.toml
14├── production
15│   ├── hugo.toml
16│   └── params.toml
17└── staging
18    ├── hugo.toml
19    └── params.toml

As shown above, the site contains four environments.

_defaultThe default configuration, which will be merged into the final configuration.
developmentDevelopment environment, the hugo server default environment.
stagingCustom environment, can be loaded by -e staging.
productionProduction environment, the hugo default environment.
Configuration fileDescription
hugo.*Hugo configuration file
params.*parameter configuration
menus.*menu configuration
languages.*Language configuration

Hugo supports configuring for a specific language, such as menus.en.toml, menus.zh-hans.toml, params.en.toml and params.zh-hans.toml as shown above.

Learn More

Monday, July 15, 2024 Friday, February 17, 2023