Markdown within block-level elements

Waylan Limberg waylan.limberg at
Wed Sep 17 23:08:28 EDT 2014

> On Sep 17, 2014, at 9:07 PM, Alan Hogan <contact at> wrote:
>> I think the spec makes it clear that the content of `<header>` should not be parsed with the Markdown syntax. As for whether the spec is right or wrong in that choice, that is another debate entirely.
> Indeed. To be clear, I am aware of Gruber’s rule (although I forget it from time-to-time as an author), and was hoping to provoke some discussion with the aim of, yes, rallying around the Common Mark decision here. 

As far as I am concerned, CommonMark is not Markdown -- more like a (much) younger sister. So when we are talking about Markdown, the behavior of CommonMark has no bearing on the matter IMO. Until Gruber changes the rules, those rules describe the only thing that is Markdown.

In fact, Babelmark has become completely useless to me now that it includes the output of CommonMark. I can't point users at Babelmark and say "that's the way they all do it." And of course, when debugging my implementation, now I have to separate the actual Markdown parsers from the non-Markdown parsers every time I'm comparing behaviors.

To be clear, I like a lot of things about CommonMark. Personally, I would take changes a little further and call it "inspired by Markdown." I look forward to when it grows up and can be a true sister to Markdown.

> I do not understand why the rule existed in the first place.
> Apart from historical reasons, are there other good reasons to avoid Markdown processing within block-level elements?

Ever have something that you don't want parsed as Markdown text, but you also don't want inside a `<pre>` tag (a math equation that will get processed by JavaScript in the browser comes to mind)? Wrapping it in a `<div>` tag is the easiest way to do that. Straightforward  and simple. Or how about when you paste in some carefully crafted HTML, like a `<canvas>` or `<svg>` element? You definitely don't want Markdown parsing that. With the current default behavior, you never have to worry. 

Yes, I think CommonMark offers a very nice compromise (relying on the existence or not of blank lines) but there are way to many existing documents that would break if the behavior was changed. The only way we can change is if we leave Markdown behind and use a new, *different* language. For example, if tomorrow GitHub swapped out their Markdown parser for CommonMark, how many of their customers' README files would suddenly be broken? I imagine there would be an outcry! As a longtime implementer of the most popular implementation in a certain language, I can't do that to my users.

When the creators of CommonMark embrace it for what it is -- a new sister language, I'll be happy to join the discussion. And I might even use it in place of Markdown in certain situations. But until then, I have no interest in pretending it is something it is not. To be clear, I like much of  the spec; it improves on many of Markdown's weaknesses, but I can't be a part of something that claims to be something it is not. I realize it's not my call, but I would prefer that any discussion of CommonMark be kept off this list -- this is a list for discussing Markdown. I've been quietly contemplating the situation until now, and now that I've shared my opinion on the matter, I won't bring it up again.

Waylan Limberg

More information about the Markdown-Discuss mailing list