The case for a `<!CommonMark>` declaration tag

[chrisalley]

I’m opposed to adding a declaration tag to CommonMark documents. While HTML is a suitable format for machines and developers, Markdown was designed as a writing format for human beings who are not necessarily developers. As the Markdown philosophy states, readability is emphasised above all else. “A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.”

I’ll address each what I see as the three main arguments in original post in turn:

@Burt_Harris

First it should do no harm. Its already supported as a 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.

The harm done is that it adds extra visual noise to the document which is not meaningful to a typical human reader. The overall aesthetic of Markdown is harmed when we add syntax intended solely for machines.

@Burt_Harris

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.

The web service could flag old posts in a database table as the legacy format and render them accordingly. This would reduce the need to add a versioning switch syntax to CommonMark in a lot of cases.

@Burt_Harris

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.

I hope that future versions of CommonMark do not break backward compatibility; any releases after 1.0 should be minor fixes and should degrade gracefully. If the goal of CommonMark is to solve the problem of multiple inconsistent implementations of Markdown then changing the spec would be creating yet another flavour of Markdown.

Extensions might create inconsistencies between documents though. In the case of extensions extra care should be made so that there is a graceful fall back to core CommonMark, preserving the semantic meaning of the extension. I’ll provide two extension examples:

~~strikethrough text~~

with the extension enabled generates the following HTML:

<s>strikethrough text</s>

and without the extension generates:

<p>~~strikethrough text~~</p>

…which still looks like strikethrough; no major harm done. Another example is the proposed definition list syntax:

Species
: Human

which generates:

<dl>
	<dt>Species</dt>
	<dd>Human</dd>
</dl>

and without the extension generates:

<p>Species: Human</p>

Not a bad fallback either. There will be some extensions that don’t degrade as gracefully. So long as the meaning remains apparent this is an appropriate solution.