« Configuring Security in Hugo
  
qutebrowser Key Bindings »

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 twitter.com/@GoHugoIO.

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

 

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 Hugo Tutorial: 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 (struct) 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 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 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$

 

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

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 ¯\_(ツ)_/¯).

Comments and questions 📝 🤔 👎 👍

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