linting YAML front matter in a Markdown file

[wesley-dean-flexion]

Suppose there's a Markdown file named people.md and its contents is:

---
title: People
key_objectives: 
  - title: Organizational Culture Development
    items:
    - Develop, implement and own a culture development
---

I'm regular markdown.

There's an error in the YAML (the Develop line should be indented two more spaces).

Because the filename (people.md) has a .md extension, MARKDOWN_MARKDOWNLINT would lint the file. However, DavidAnson/markdownlint defaults to ignoring front matter; if told not to ignore it, it would likely throw errors when the YAML (or JSON or TOML) content doesn't meet Markdown linter rules.

tl;dr: markdownlint won't lint the YAML and the YAML error will go unnoticed.

If, adrienverge/yamllint were passed the file (i.e., if YAML_YAMLLINT matched .md files), it, too, would fail when the Markdown content didn't validate as proper YAML. Insert the same logic for JSON and TOML.

So, it would be nice if there was a mechanism to extract the front matter from a Markdown file and allow the proper linter to lint that content.

I wrote a script to read STDIN, grab what's between the first and second --- , and write it to STDOUT. My thinking was something like:

1. match a .md file
2. create a temporary file (mktemp)
3. extract the front matter from that file and write it to the temporary file
4. lint the temporary file with yamllint
5. use sed to rewrite the filename of the linter from the temporary file back to the original so the errors correspond to the real file and not the temporary one
6. remove the temporary file

Here's a link to a Bash script I put together just to see how difficult it would be to extract the front matter. The script doesn't do any linting or handle any files -- it just reads from STDIN and writes to STDOUT. The link'll probably break if/when the PR with which it's associated is merged:

https://raw.githubusercontent.com/GSA-TTS/tts.gsa.gov/11c59be4a36d4b43a551338994d7baf2be04c634/bin/extract_front_matter.bash

So.. would something like this (i.e., a tool to lint front matter from Markdown files) be something that MegaLinter would want to include? Any thoughts?

[wesley-dean-flexion]

A couple of thoughts..

The markdownlint configuration to ignore front matter mentions that the options.frontMatter setting...

[i]gnores YAML, TOML, and JSON front matter

and it links to the Jekyll documentation describing front matter.

Commonmark and GFM specifications are silent with regards to front matter; as a result, it's not directly, explicitly, specifically clear if front matter may only be YAML or if it may be some other format (JSON, TOML).

In 2015, moonwave99 asked on Stack Overflow Is there a YAML front matter standard / validator?

to which joemailer responded:

The closest thing to a standard would be Jekyll's Front Matter description. Everything else seems to follow that. If Jekyll didn't invent Yaml Front Matter, they were one of the first notable projects to feature it.

[...]

So, while there is no formal specification [...]

Therefore, I'm thinking:

1. front matter is not a standard with formal recognition
2. front matter may include a subset of the YAML specification (it doesn't appear that there's any provision for front matter supporting multiple YAML documents)
3. front matter is usually YAML, but given that there's no formal spec, there's no formal reason why it couldn't be JSON, TOML, etc.
4. if front matter is something other than YAML, how does one determine which format is specified?

• YAML uses colons to separate keys and values; TOML uses equals signs
• JSON lists start with open square brackets; TOML tables start with open square brackets

point: it doesn't look very straight-forward to determine if a given front matter block is YAML, JSON, or TOML

It's entirely possible that a single repository has Markdown files that have YAML, JSON, and/or TOML front matter blocks so it may be problematic to specify a configuration variable that says to use a YAML linter on all Markdown front matter.

Running file on a few YAML, TOML, and Markdown files returns some variation of ASCII text or Unicode text while a JSON file was correctly determined to contain JSON data. So, running file on the extracted front matter is unlikely to yield a good guess as to which linter to use.

Maybe instead of a singular front matter linter, there was one for each supported format (e.g., MARKDOWN_FRONTMATTER_YAMLLINT). If that's the case, it could quickly get ugly with regards to specifying which linter(s) to use with which file(s).

Perhaps it may be useful to encourage folks to use a filename specification like filename.yaml.md or filename.fmyaml.md. As both YAML and TOML support comments starting with # and file can tell us when we're looking at JSON data, perhaps a comment like (?i)^[[:space:]#]*(YA|TO)ML\b could be used to provide a hint as to which linter to use.

[wesley-dean-flexion]

@nvuillam

I'm thinking of creating MARKDOWN_FMLINT which would be exactly like yamllint but with something like this script copied in to run in front of yamllint.

https://github.com/GSA-TTS/tts.gsa.gov/blob/staging/bin/yaml_lint_front_matter.bash

Any thoughts? Is there a better or cleaner or more pythonic way you would suggest?

[nvuillam]

@wesley-dean-flexion your request seems quite specific :)
Why don't you use PRE_COMMANDS or YAML_YAMLLINT_PRE_COMMANDS to run your script before yamllint ? :)

[wesley-dean-flexion]

fmlint() {
  for markdown_file in "$@" ; do
    temp_file="$(mktemp)"
    cp -f "$markdown_file" "$temp_file"
    sed -Eze 's/((^|\n)---.*?---(\n|$)).*/\1/' < "$temp_file" | yamllint --options-go-here - | sed -Ee "s|$temp_file|$markdown_file|g"
    rm -f "$temp_file"
  done
}