What changed in CommonMark?

Spec
1

In general, as little as possible!

The goal of CommonMark is not to redefine what Markdown is, or change the syntax, but make it parseable and predictable.

We did try to address some minor persistent Markdown complaints we’ve seen across the millions of users in GitHub, Stack Exchange, Reddit, Discourse, pandoc, and babelmark. John MacFarlane documents them here:

In a few cases, I have departed slightly from the canonical syntax description, in ways that I think further the goals of markdown as stated in that description.

There are only a few places where this spec says things that are contradict the canonical syntax description:

  • It allows all puncutation symbols to be backslash-escaped, not just the symbols with special meanings in markdown. I found that it was just too hard to remember which symbols could be escaped.

  • It introduces an alternative syntax for hard line breaks, a backslash at the end of the line, supplementing the two-spaces-at-the-end-of-line rule. This is motivated by persistent complaints about the “invisible” nature of the two-space rule.

  • Link syntax has been made a bit more predictable (in a backwards-compatible way). For example, Markdown.pl allows single quotes around a title in inline links, but not in reference links. This kind of difference is really hard for users to remember, so the spec allows single quotes in both contexts.

  • The rule for HTML blocks differs, though in most real cases it shouldn’t make a difference. (See here for details.) The spec’s proposal makes it easy to include markdown inside HTML block-level tags, if you want to, but also allows you to exclude this. It is also makes parsing much easier, avoiding expensive backtracking.

  • It does not collapse adjacent bird-track blocks into a single blockquote:

      > this is two
  
  > blockquotes
  
  > this is a single
  >
  > blockquote with two paragraphs

  • Rules for content in lists differ in a few respects, though (as with HTML blocks), most lists in existing documents should render as intended. There is some discussion of the choice points and differences here. I think that the spec’s proposal does better than any existing implementation in rendering lists the way a human writer or reader would intuitively understand them. (I could give numerous examples of perfectly natural looking lists that nearly every existing implementation flubs up.)

  • The spec stipulates that two blank lines break out of all list contexts. This is an attempt to deal with issues that often come up when someone wants to have two adjacent lists, or a list followed by an indented code block.

  • Changing bullet characters, or changing from bullets to numbers or vice versa, starts a new list. I think that is almost always going to be the writer’s intent.

  • The number that begins an ordered list item may be followed by either . or ). Changing the delimiter style starts a new list.

  • The start number of an ordered list is significant.

  • Fenced code blocks are supported, delimited by either backticks (```) or tildes (~~~).

4 Likes