Metadata syntax (was Universal syntax for Markdown)

John MacFarlane jgm at
Mon Sep 19 20:55:29 EDT 2011

+++ Sam Angove [Sep 20 11 10:33 ]:

> On Mon, Sep 19, 2011 at 3:47 AM, John MacFarlane <jgm at> wrote:

> > Another major problem, in my view, is that if a document starts

> > with a phrase followed by a colon, it gets swallowed into metadata:

> > [...]

> > Also, because this is recognizable as metadata wherever it occurs

> > in the document, one could then drop the requirement that the

> > metadata occur at the top of the document, which I think is

> > undesirable.


> Another alternative is to re-use the syntax that Markdown already has

> for document-level metadata:


> [1]:

> [^f1]: A footnote here


> Perhaps:


> [title]: Here is the title.

> [abstract]: The abstract here.


> As with footnotes, lists etc., indented lines continue the block.

> [author]: John



> Not quite as natural as the unbracketed version, but more consistent

> with Markdown conventions and less likely to cause unpleasant

> surprises. (The obvious risk is the potential for collision with

> reference links, but I think it is quite minor, and could be minimized

> by special-casing metadata at the beginning of a document.)


> >From a syntax perspective, the idea would be that reference link

> definitions, footnotes, MMD-format references etc. are all removed as

> metadata. Keys starting with "^" are treated as footnotes, values

> matching the URI/title form may be re-inserted as reference links,

> etc.

I think this is a very nice idea. Authors would have to be careful
not to use the same label for a reference link and a piece of
metadata, but I don't see that being a big problem.

If people didn't like the brackets, then I think the next best
idea would be to require a delimiter of some kind, but keep
the capacity for multiple paragraphs as with footnotes:

title: Here is the title.
author: John
abstract: The abstract here.

As with footnotes, lists etc., indented lines continue the block.


More information about the Markdown-Discuss mailing list