Compartmentalizing Hugo Settings With a config Directory
Updated  2022-January-14

Page contents

News

2022-January-9  Published this evolving⁠[1] article.

 

Using a config.yaml, config.toml, or config.json file

For a simple Hugo project, a single configuration file is fine. For example, here is the structure of the TGIH project that is used in Infinite Ink’s Hugo Tutorial: Themeless & Gitless Introduction to the Hugo Static Site Generator:

.
└── TGIH/
    ├── archetypes/
    ├── assets/
    ├── content/
    ├── layouts/
    ├── static/
    └── config.yaml

Note that a Hugo configuration file can be specified in JSON, TOML, or YAML format and any of the following file names can be used as a configuration file name.

  • config.json

  • config.toml

  • config.yaml

Throughout this article, I use YAML format.⁠[2]

 

Using a config directory

Starting with Hugo v0.53, you can put your configuration file(s) in a config directory. For example, the following structure is equivalent to the above structure.

.
└── TGIH/
    ├── archetypes/
    ├── assets/
    ├── config/
    │   └── _default/
    │       └── config.yaml
    ├── content/
    ├── layouts/
    └── static/

 

One of the advantages of using a config directory is that you have the option to put a configuration section (struct) into its own file. For example, Infinite Ink’s old (uncompartmentalized) config.yaml looked like this:

config.yaml (before compartmentalizing)
## next discussed in www.ii.com/themeless-gitless-intro-hugo/#_enableemoji
enableEmoji: true

## next discussed in www.ii.com/hugo-sitemapdottxt/
sitemap:
  filename: sitemap.txt

⋮

## next discussed in www.ii.com/hugo-security-config/
security:
  enableInlineShortcodes: true
  exec:
    allow:
    - ^asciidoctor
    - ^pandoc
    osEnv:
    - .*
  funcs:
    getenv:
    - ^INFINITEINKROOT$

 

After moving the above security section to its own file, the Infinite Ink directory structure looks like this:

.
└── INFINITEINK/
    ├── archetypes/
    ├── assets/
    ├── config/
    │   └── _default/
    │       ├── config.yaml
    │       └── security.yaml   ←👀
    ├── content/
    ├── layouts/
    └── static/

 

And the config/_default/security.yaml file looks like this:

security.yaml (after compartmentalizing)
enableInlineShortcodes: true
exec:
  allow:
  - ^asciidoctor
  - ^pandoc
  osEnv:
  - .*
funcs:
  getenv:
  - ^INFINITEINKROOT$

 

When the security section is moved from config.yaml to security.yaml, the leading security: key must be removed.

 

To learn about the above security settings, see Infinite Ink’s Configuring Security in Hugo.

 

Hugo configuration references

See also

Endnotes


1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. I prefer YAML to TOML because I do not want to have to deal with TOML tables.

Comments and questions 📝 👍 👎 🤔

Your public comment or question might immediately improve this page or help me to (eventually) improve this page.