Add support for YAML metadata blocks

[reasonableperson]

Hi, thanks for releasing this library! Pandoc's yaml_metadata_block extension allows you to insert front matter at the top of a Markdown document in the form of an arbitrary YAML object delimited by ---. It would be useful for Rimu also to support this.

YAML is implemented in std/encoding, so I was able to put together a rough patch pretty easily. However, it breaks the API by awkwardly changing the type of the exported render function to return a [metadata, html] tuple. The name render suggests that Rimu is not intended to do anything other than consume Markdown and emit HTML.

Let me know if you're interested in a more comprehensive PR that implements this properly, perhaps by exporting a metadata function. Otherwise, I'm happy to implement this in my own code, and you can just close this issue as a record of the fact that YAML metadata blocks are out of scope for Rimu.

[srackham]

I haven't used Pandoc but from what I can gather the Pandoc YAML extension is a mechanism for assigning Pandoc metadata from YAML.

Rimu has a native metadata mechanism in the form of macro definitions (https://srackham.github.io/rimu/reference.html#macro-definitions).

The hindsite static website generator can consume TOML and YAML headers in Rimu documents and uses a similar technique to the one you've used but the headers are preprocessed and then the Rimu document body is rendered sans the header. See https://srackham.github.io/hindsite/index.html#front-matter-header

What are the use-cases for this mechanism?

Why YAML specifically? Why not e.g. TOML or JSON or ...?

[reasonableperson]

Thanks for the pointer to hindsite. The use case I have in mind is essentially the same: to use Markdown (or Rimu) files to store documents and associated user-defined metadata in my application, using a more or less standardised, human-readable format. My idea is also similar to a plain text format for tiddlers in TiddlyWiki, without the restriction to key-value pairs for user-defined metadata.

The only reason for mentioning YAML specifically is that it's supported by Pandoc and other Markdown software. I hadn't seen front matter done with TOML before, but I prefer it. To me, this seems like a natural feature to support in the document format itself. Doing so allows for the front matter syntax to be highlighted using a standard syntax highlighting configuration file for the document format.

I did consider using macros to record metadata (eg. tags) in a Rimu document, but in order to use that metadata in my JavaScript application, I'd have to get Rimu to render it to HTML and parse it out again via data attributes or something. The approach of handling my input as two concatenated documents, in YAML and Rimu format respectively, seems cleaner than this.