Implement YAML block additional feature

[abock]

This implements support for parsing YAML blocks and front-matter following the Pandoc rules:

1. Delimited by three hyphens (---) at the top
2. Delimited by three hyphens (---) or dots (...) at the bottom
3. May occur anywhere in the document, but if not at the beginning must be preceded by a blank line.

BlockTag.YamlBlock is defined, and FencedCodeData is used to store the closing fence character (either - or .) and to indicate whether the closing fence has been seen in the same manner as BlockTag.FencedCode.

YAML support may be enabled via two-flavors:

1. CommonMarkAdditionalFeatures.YamlBlocks: this allows for any number of YAML blocks anywhere in the document.

2. CommonMarkAdditionalFeatures.YamlFrontMatterOnly: allows for exactly one YAML block, defined on the first line of the document.

The HTML formatters treat BlockTag.YamlBlock blocks the same way as BlockTag.FencedCode blocks, except that instead of writing the info string, a class="language-yaml" attribute will be written.

[Knagis]

Seems ok, however a few notes (disclaimer - I haven't ever actually used yaml):

1. would it make sense to support that the yaml marker (---) could be indented, the same as fenced code?

2. Perhaps the fence length could be variable? Looking at the yaml spec, --- is used to separate multiple yaml documents within the same stream. So if I would want to enter such multiple documents within the markdown text, I could use a 4 char fence ---- and then the internal three char --- would be handled by the yaml parser itself.

3. at least the wikipedia page shows examples where the --- fence is followed by a comment, perhaps it should be supported?

--- #yaml metadata
- here
- goes
- yaml
--- #end of yaml metadata

markdown continues...

[abock]

I don't particularly have any objection to extending the YAML support to be more like fenced code blocks. I implemented it to strictly conform to Pandoc's handling of these blocks, however (at least per their documentation).

From a document processing perspective, extending YAML support in the way you describe could certainly be useful. In particular, it could allow for specifying the metadata format (e.g. not restricted to implied YAML).

The one thing I do not quite feel right about is providing support in the HTML formatter for these blocks at all, or at least by default, since it's specifically meta data.

I think from a CommonMark.NET perspective, using this additional feature should imply that you are always doing your own tree processing, since you need to separate metadata from markdown.

So I propose:

1. I'll implement your ideas (1, 2, 3)
2. Rename anything "YAML" specific to "Metadata" (e.g. YamlBlock → MetadataBlock
3. Have the HTML formatters just ignore MetadataBlock. Perhaps the formatter could also take a delegate for rendering these? For instance, GitHub will render the structured YAML as a table for markdown content with front-matter, but this is out of scope for CommonMark.NET, since it does not understand YAML itself.

[Knagis]

Yes, using the more generic Metadata seems to be a good idea.

As for the HtmlFormatter - my guess is that the best default behavior would be to not render them at all. At least situations where I see I could be using the metadata it would not be something that I would want to be visible in the output.

As for the delegate - I think that the ability to derive from HtmlFormatter should be enough.