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
}

[wesley-dean-flexion]

@nvuillam I thought I responded to the comment about PRE_COMMANDS but as I look back in the thread, clearly I did not.

Is the suggestion that I use PRE_COMMANDS to rename the files so that yamllint will pick up the files I want to have linted (and then POST_COMMANDS to rename them back, right?)?

Perhaps my understanding of PRE_COMMANDS is mistaken. My mental model is that they're a list of commands that are run before a linter is run, but they're not connecting the file descriptors from the PRE_COMMANDS to the linters.. right? That is, STDOUT from PRE_COMMANDS doesn't become STDIN for the linter. Correct? By extension, STDOUT from linters doesn't become STDIN to POST_COMMANDS.. right?

Please forgive this mess -- it's not well considered.

if YAML_YAMLLINT_PRE_COMMANDS is used to rename a file being linted from .md to .yaml and because cli_lint_mode for yamllint is list_of_files and YAML_YAMLLINT_POST_COMMANDS is used to rename the file from .yaml to .md.. how does yamllint know to lint the .yaml file and not the .md file that it was passed?

Or does PRE_COMMANDS do the copying / extracting and writing the output to .yaml files so that MegaLinter picks up the changed file when it generates the list of files to lint..? the newly-created file would have a .yaml extension so yamllint would run on it.

For what it's worth, the project I'm trying to lint includes Markdown files that are simply Markdown (i.e., they have no YAML front matter), some are basically YAML files with a .md extension, and some are Markdown files with YAML front matter. It wouldn't work to convert all the Markdown to YAML and run yamllint on it.

Ideally, the output generated from doing the linting would have the original filenames (i.e., .md extensions) and not those of temporary files or those with a .yaml extension. We can do that with some file / filename manipulation or passing output through sed.