Metadata syntax (was Universal syntax for Markdown)

[John MacFarlane]

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

> On Mon, Sep 19, 2011 at 3:47 AM, John MacFarlane <jgm at berkeley.edu> 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]: http://example.com/

>    [^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.
    ---

John