The Hugo static site builder allows configuration using TOML, YAML or JSON. This offers great flexibility to the site author or theme creator and allows for great choices for the geek using Hugo as the choice to create a fabulous site.
Like many authors I started hosting a site using WordPress. I used a conversion program to import my old blog posts in Hugo. I carefully choose a Hugo template and started hacking away. I ended up with a mixture of Hugo frontmatter in TOML and YAML.
That is not ideal, it is best to choose a standard (and there are many choices in standards) and stick to it. But which one is the most appropriate? Decisions, decisions,…
TOML is the new kid in town. So I started to look for recommendations for using YAML as compared to the oldie JSON.
What I learned was:
- Technically YAML is a superset of JSON.
- JSON wins as a data interchange format. But for configuration, it is we humble humans that need to understand the format and write it without errors.
- YAML is more robust in embedding other serialization formats such as JSON or XML. For complex object serialization, or for grammar definitions, YAML is preferred.
- YAML supports comments, which is important if used for configuration.
- YAML does not allow duplicate keys, which can occur by accident if hand coding a configuration file.
- YAML uses indentation rather than bracketed syntax. For Python developers, this is great. For others, this is a poor design choice.
There is a ton more discussion, but based on the above, YAML still seems the best for configuration. What about the differences between YAML and TOML?
- TOML is designed to be a minimal configuration file format that is easy to read by humans.
- TOML might be harder to read for deep nested structures, but we don’t have that often within configuration files.
- TOML is a cleaner format. YAML is still better if we communicate between applications.
- TOML seems to gain popularity fast.
Not much going between the two choices.
It is great that Hugo offers flexibility, but this can confuse newbies like me. After all, it will be your personal choice whether to use TOML, YAML or JSON.
I chose TOML based on the reasons documented earlier. You might have other and maybe better insights. Let me hear it!
From now onwards, all configuration details in the how-to section will use TOML. If your choice is YAML or JSON, fear not, conversion is not that difficult. But I recommend to stick with one choice, this will make maintenance of your site a lot easier. After all, you should concentrate on writing great insightful posts rather than spending time over nitty gritty configuration details. But we are all geeks and sometimes we like to delve deeper. Remember to have fun! Looking forward to visit your sites.