A convention for flavor declaration


Proposals for document type declarations haven’t gained traction in the past. The objections are that they add noise to documents or, worse, are rendered into views by existing markdown software.

As a work-around, markdown flavour is sometimes indicated by authors in their documents, typically by linking to the relevant specification. Experienced authors use link reference definitions.

For example, from the README.md of the Java reference implementation:

Java library for parsing and rendering [Markdown] text according to the
[CommonMark] specification (and some extensions).
[CommonMark]: http://commonmark.org/
[Markdown]: https://daringfireball.net/projects/markdown/

If a convention for indicating document flavor were to be established then parsers could use it to render documents according to the author’s intention, rather than relying on the consumer’s context.

I propose that a link reference definition with a “well known” name and URI be used to indicate markdown flavor.

For example, given a document containing a link reference with the name markup associated with a link to the original Markdown spec, a parser should render the document according to John Gruber’s original spec:

Hi, I'm a document written in [Markdown][markup].
[markup]: https://daringfireball.net/projects/markdown/syntax

Dangling link references are not rendered, so it’s safe to indicate document flavour this way even if the reference is not used:

Hi, I'm written in GFM.
[markup]: https://help.github.com/categories/writing-on-github

All that’s needed to make this work is a central database of well known URIs that parsers can refer to. Luckily we already have one.


We already have media types where available.




As part of CommonMark I don’t think this is needed since CommonMark does not have flavours. Any extensions such as tables would be superset of CommonMark, rather than a flavour, and would still need to look readable with the extension rendering turned off.

As a convention for use in the wider Markdown community, perhaps this would be useful in some cases, but outside of the scope of CommonMark.