I want to make the point that there are two ways in which we might
think of a YAML metadata section fitting in to documents.
A. One is to consider think of YAML metadata blocks as part of CommonMark,
adding it to the spec, etc. With this method, metadata would be part of
the AST produced by a CommonMark parser. (That’s how it is in pandoc.)
B. Another is to think of a document like:
---
title: My title
author: Me
---
Starts here...
as really the combination of two separate documents – one, a YAML
document, which ends at the second ---, the other, a CommonMark
document.
A processor would then divide the two documents, parse the YAML document
with a proper YAML parser (or, if it likes, just skip it), and parse
the rest with a CommonMark parser.
The processor could use the values gleaned from the YAML document in
any way it likes – interpolating them into templates, for example,
and even perhaps running their string contents through a CommonMark
parser. The CommonMark spec wouldn’t need to know about this.
(This is how it is done in Jekyll, for example.)