Metadata syntax (was Universal syntax for Markdown)

[John MacFarlane]

+++ 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