Universal syntax for Markdown

Waylan Limberg waylan at gmail.com
Tue Aug 16 11:50:25 EDT 2011

On Tue, Aug 16, 2011 at 1:07 AM, David Chambers
<david.chambers.05 at gmail.com> wrote:

> First let me say that this thread has me excited. There's a great deal of

> constructive discussion, and a surprising number of "I agree" replies.

> I'll add my two cents on the particulars that have been discussed herein.

> Metadata

> Just about every Markdown document I create includes metadata (for date,

> time, and time zone, and sometimes tags). I couldn't live without it, but as

> a user it doesn't matter to me whether these data are processed by the

> Markdown library itself or, as Waylan suggested, by "a separate […] library

> (like YAML) which reads and removes the metadata".

> I think Alan's suggestion that Markdown should define syntax for a metadata

> section (while ignoring the contents of such sections) is an excellent one.

Just an FYI, but the section separator that Alan mentioned is actually
part of YAML. In fact, IIRC without it the YAML parser would consider
it an invalid document. I guess the point is that what marks the
meta-data could be dependent on what format is used for meta-data.
That might be hard to define in a Markdown spec if we leave it open
for any meta-data format.

> Definition lists

> The fact that including more than one definition for a given term is an

> uncommon requirement should not preclude such use cases from being

> accommodated. Rather than thinking in terms of the "rendered" content (be it

> HTML, PDF, or some other format) we should first think in terms of what our

> content means and how best to express that meaning in a structured fashion.

> Definition lists are a good case in point. What is a definition? Text that

> explains the meaning of or describes some thing. There therefore exists some

> relationship between the definition and the thing it defines. Also, there

> may be several ways to describe one thing. What is the relationship between

> various definitions for a particular thing? Are they equally important? Are

> they sequential? Can they be grouped in some way? Can one description apply

> to more than one thing?

Valid questions. Interestingly, the HTML5 spec answers some of this.
In fact, the HTML5 spec [1] calls `<dl>` a "description list" which
expands beyond definitions. It states: "Name-value groups may be terms
and definitions, metadata topics and values, questions and answers, or
any other groups of name-value data." And then proceeds to provide
examples, one of which specifically provides two terms for a value. I
don't see any reason why a markdown variant wouldn't support all the
same use cases.

[1]: http://developers.whatwg.org/grouping-content.html#the-dl-element

\X/ /-\ `/ |_ /-\ |\|
Waylan Limberg

More information about the Markdown-Discuss mailing list