Add documentation on how to use the Front Matter Plugin

[minchinweb]

Context

Pulling front matter out of a Markdown file makes the files much more helpful, but is much more complex to use that most render rules (like, e.g. superscript) because it's not obvious how to get the metadata out of the HTML that the rendered spits out!

Proposal

I have a working process here --> https://github.com/minchinweb/minchin.pelican.readers.commonmark/blob/master/minchin/pelican/readers/commonmark/reader.py#L76

But it involves processing the Markdown file twice -- once for the front matter and a second time to set the HTML body. Is this really the most effective way to do this? i.e. do I really need to process the source file twice?

Also, pulling the metadata out seems to involve working from the AST tree, which would be painful to somehow work out from the plugin's source code. (I must have copied it from somewhere, but I have no idea where...).

Tasks and updates

• document how to add the front matter plugin
• document how to process a markdown file and get metadata and HTML content out in one go
• document how to post-process the resulting metadata
• note tips and tricks, solutions to common problems, etc