Compartmentalizing Hugo Settings With a config Directory
Updated  2022-July-2

Page contents

News

Ongoing  According to Repology, the latest packaged Hugo is version newest packaged version of Hugo. To keep up with Hugo releases, see github.com/gohugoio/hugo/releases, discourse.gohugo.io/c/announcements, or @GoHugoIO@twitter.com.

2023-January-9  As of today, this evolving⁠[1] article has been on the web for 1 year.🎂

 

Using a root-based config.yaml, config.toml, or config.json file

For a simple Hugo project, a single configuration file in the project root⁠[2] is fine. For example, here is the structure of the TGIH project used in Infinite Ink’s TGIH: Themeless & Gitless Introduction to the Hugo SSG.

.
└── TGIH/                        ⟵project root
    ├── 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 can be used as the file name.

  • config.json

  • config.toml

  • config.yaml

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

 

Using a config directory

Starting with Hugo v0.53, you have the option of putting 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 can put a configuration block into its own file. For example, Infinite Ink’s original (uncompartmentalized) config.yaml looked like this:

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

## next discussed in www.ii.com/yaml-atoms-maps-lists/
cacheDir: 'C:\Hugo_cache_infiniteink'

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

outputFormats:
  html:
    isPlainText: true



⋮

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

 

After moving the above security block 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$
http:
  methods:
  - none
  urls:
  - none

 

‼
When the security block 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

For more about Hugo, see Infinite Ink’s…

 

Endnotes

1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. Project root is also known as project base directory, project root directory, project working directory, project directory, root, or workingdir.
3. I prefer YAML to TOML because I do not want to have to deal with TOML tables. To learn about YAML, see Infinite Ink’s YAML Includes Atoms, Maps, and Lists (featuring the string ¯\_(ツ)_/¯).

Discuss or share 📝 🤔 🐘