Metadata syntax (was Universal syntax for Markdown)

Fletcher T. Penney fletcher at
Mon Sep 19 14:34:48 EDT 2011

I wonder how often multi-paragraph metadata comes up in real world use? Something like an abstract, IMO, shouldn't be metadata - it should be part of the document. How to *display* that section graphically (e.g. smaller font?, narrower width, etc.) is a problem for CSS/LaTeX/ODF/whatever - *not* for Markdown itself.

I published a book via Lulu (a friend's PhD thesis) using MMD - it had an abstract, dedication, acknowledgements, preface, ToC, lists of figures, etc. Each of which was formatted appropriately, without using metadata for any of it. I customized an XSLT to generate the LaTeX I desired, and the result was fantastic.

The only problem I have run into with MMD's metadata is that it would be nice to support markup inside some fields but not all, and that has rarely been a problem for me. This was easily remedied in MMD 2, but trickier in MMD 3.

I think the best shot at consensus is a basic syntax for general metadata (obviously I'm partial to MMD ;) that covers 90% of what people do. Then a more complicated shared syntax for those variants that want to support the "kitchen sink" approach to metadata.

Not to repeat myself, but I again think we're approaching this from the wrong end. If there's going to be a consensus, I think it's going to have to start with a shared philosophy for the standards. Each variant may end up with it's own philosophy outside of that, but there has to be a common vision for the purpose of the standard.

Until that happens, I don't think we'll get anywhere trying to sort out specific implementations for specific features - we don't have a shared understanding of the problem we're trying to solve.


On Sep 19, 2011, at 11:12 AM, John MacFarlane wrote:

> +++ David Chambers [Sep 18 11 15:08 ]:

>> If we want to avoid defining our

>> own serialization format, we have two options: we can adopt an existing

>> format (such as JSON or YAML), or we can hand off the responsibility to

>> application developers.


> Yes, I agree, and I certainly agree that we shouldn't go down the path

> of reinventing YAML. My proposal was to use lua as a data description

> language, as it is more texty than json, less quirky than YAML, and

> more flexible than either. But I don't really expect to get consensus

> on that.


> It seems to me that there are three levels at which we might hope

> to achieve consensus about metadata in markdown:


> 1. Agreement about which bits of the document are metadata, so

> these won't be processed as part of the document's text.


> 2. Agreement about a key-value format, so that all implementations

> can extract metadata into key/value pairs, with literal string

> values, in the same way.


> 3. Agreement about how the values are to be parsed into structured

> data, which bits are to be parsed as markdown, etc.


> Consensus on 1 would be useful, because it would prevent your metadata

> from turning into displayed garbage when processed with another markdown

> implementaiton.


> My own proposal on 1 was to put metadata inside specially marked HTML

> comments. An advantage is that there is *already* agreement among

> implementations not to make this part of the displayed document, so

> no agreement is needed. In effect, my proposal already achieves

> consensus on 1.


> Another possibility would be to put metadata inside '---' and '---'.

> This would solve two problems with MMD metadata: it would allow it

> to occur anywhere in the document, and it would avoid unwanted results

> when you happen to have a colon in the first line of your text.


> As for 2, a minimal modification from MMD style metadata would be

> to allow blank lines in fields, by requiring continuation lines

> to be indented four spaces.


> ---

> field1: Value one.

> Continued here.


> Another paragraph.


> field2: Next field.

> ---


> This would work best if we had something like the '---' '---'

> delimiters, since otherwise you have even more opportunities for

> unwanted captures (a blank line doesn't end metadata).


> John


> _______________________________________________

> Markdown-Discuss mailing list

> Markdown-Discuss at


Fletcher T. Penney
fletcher at

More information about the Markdown-Discuss mailing list