Let’s discuss the interpretation & advantages of using an optional
<!CommonMark> directive at the beginning of a CommonMark document.
First it should do no harm. Its already supported as a [declaration] (http://jgm.github.io/stmd/spec.html#declaration) by the proposed CommonMark spec. Based on this, any good CommonMark processor will pass it through into the HTML output unaltered. Browsers, not recognizing the name CommonMark, will simply ignore it. The typical human reader would be unimpressed, which is good.
On the other hand, a simple document pre-processor could recognize the declaration, and choose to route the document to a CommonMark compliant processor vs some legacy document processor like markdown. This provides an upgrade path for applications and web services that want to allow users move away from some legacy markdown flavor without trying to upgrade the world.
As the CommonMark specification evolves, embedding a version number in a document’s declaration could allow a pre-processor or sophisticated CommonMark processor to customize the parsing for with strict compatibility with an older version of CommonMark a document might have been written for. Admittedly, there’s work to be done to enable this, but done correctly it will allow us to evolve CommonMark in a planned way without slavish attention to compatibility stifling invention.
Such a CommonMark declaration could specify the flavor of the document containing the declaration. For example, if I make the first line of my document say
<!CommonMark GFM/1.0>, my intent would be to reference some (as of yet non-existant) specification of what the GFM flavor of CommonMark does differently.
What we need next is a consistent plan for identifying versions of the specification in a declaration. Such a plan should allow for both official sanctioned specification versions, and for unsanctioned/proposed versions of the specification. A version should correspond to a URI or URL, and if its a URL, there should be a idempotent (unchanging) version of the specification retrievable at that location.
Clearly the versions identifiers for sanctioned versions should be concise, and we can leverage a default URL base for the version specified in a
<!CommonMark> declaration, for example http://www.commonmark.org/v/. [Don’t bothy clicking on that, it doesn’t exist yet, just a proposal.]
There’s more to say about choosing URLs to represent versions, but I’m about written out. What do you think?