0002: Use YAML Front Matter

Context

We are planning to use Hugo as SSG for this project and host it’s source code on GitHub.

We would like to make ADR archetype to manage ADRs through hugo new content adrs/NNNN-title.md. Hugo provides these available formats for front matter:

• YAML
• TOML
• JSON

We want to select a front matter format that would work well with both GitHub and Hugo.

[!NOTE] YAML frontmatter values are only for GitHub Docs, not for regular frontmatter rendering

Decision

Use YAML metadata because GitHub does not support TOML and JSON

The reason is GitHub’s support for YAML front matter. If they would support TOML front matter, we would change. But they don’t.¹

Alternatives

JSON

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.²

Verdict: Not acceptable. JSON is too verbose for front matter usage, and GitHub does not support it for front matter usage.

TOML

TOML aims to be a minimal configuration file format that’s easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.³

Verdict: Not acceptable. TOML is too verbose when writing deep heirachical data, but this is should not be a big issue for front matter. The main one that GitHub does not support it for front matter usage.

Consequences

Pros:

• We can ensure that formatting and rendering of front matter will be consistent across different tools and services.
• YAML is pretty ubiqutos format and there are a lot of additinal tooling for it.

Cons:

• Hugo uses TOML by default, which means we will have to ensure that YAML front matter is correctly enabled. AFAWK currently Hugo determines front matter autmatically:

  Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content.⁴

• YAML is riddled with issues, that led to creation of tools like StrictYAML, which may lead to parsing or rendering issues down the line.

Resources

• Using YAML frontmatter