Browser docs

Configuration Structure

February 17, 2023 2 min read Configuration Docs
On this page

This article will try to briefly introduce Hugo’s configuration structure so that you can better understand the configuration in the documentation, even if you are new to Hugo.

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.* as the configuration name to distinguish the configuration of Hugo from other projects.

HB requires Hugo 0.110.0 and above, and the configuration in the documentation is named hugo.*.

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.

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

As shown above, the site contains four environments.

EnvironmentDescription
_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.

Usually we need to preview other environments locally, such as the production environment, by simply passing -hugo server -e production -b http://localhost:1313 -p 1313.

Configuration fileDescription
hugo.*Hugo configuration file
params.*parameter configuration
menus.*menu configuration
languages.*Language configuration

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