Metadata in Markdown

Most content I write these days is written in Markdown. Sometimes I need to include metadata. But bog-standard Markdown lacks explicit metadata syntax. So, what to do?

The obvious move is to introduce some kind of metadata syntax to the beginning of the document. But which? There are so many to choose from! And, unfortunately, tools in the wild have picked all of them. Markua uses a JSON block. Mmark uses TOML. kramdown-rfc and Scolarly Markdown both use YAML. Bikeshed uses a bespoke metadata format embedded in a <pre> element.

Picking one of these metadata formats makes your documents incompatible with Markdown processors that don’t know about it. You’ve drastically reduced the set of tools you could potentially adopt in your toolchain. Worse still, the HTML that comes out of such a tool will include the metadata as visible content. It’ll look like gobbledygook.

Ideally, there’d be a metadata format that will be preserved by tools that don’t understand it and that is invisible in the HTML that comes out of those tools.

It turns out that regular Markdown already has such a mechanism after all. From the documentation:

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

We can use HTML directly, and of course HTML has a <meta> element. Markdown processors preserve <meta> elements and they’re invisible by default. So that’s sorted. Go ahead and use <meta> elements (or a more appropriate element when there is one) to include metadata in Markdown documents.