What are the main rendering differences between Markdown and CommonMark?

Note

Markdown is going to refer to rendering based on Sundown’s implementation of Markdown language, as there is no common formal specification.

CommonMark is going to refer to rendering based on CommonMark standard.

Linking

A URL can’t contain spaces, which must be percent-encoded to %20. Our old Markdown renderer took them as-is producing invalid link when given the input.

[link](/url with space)

CommonMark insists on valid URLs—link above wouldn’t be interpreted and displayed as plain text instead. In order to display the link, it needs to be escaped properly.

[link](/url%20with%20space)

List rendering

Main issues usually arise with heavy list usage.

List continuation

The problem arises when you use two spaces for a paragraph nested in the list:

1. first list item

  with nested paragraph

1. second list item

In this case, “with nested paragraph” is treated as a paragraph inside the list item in Markdown, but in CommonMark, it’s treated as being after the list item, breaking indentation and continuation.

If the paragraph is indented to be nested under the first list item, please use four spaces from now on:

1. first list item

    with nested paragraph

1. second list item

Nesting lists

Markdown always interprets the nested item list always as a nested item list.

- Item

    - Nested Item

This is true for CommonMark as well. However, the problem arises when one more new line is added:

- Item


    - Nested Item

This additional new line conflicts with syntax for code blocks—and CommonMark gives it a preference (where Markdown gave preference to the nested list).

If you want a nested list, you need to delete that one empty new line.

Headings in list

In Markdown, you can have list items that start with a hashbang.

- # Heading

In CommonMark, this is interpreted as a heading in a list, which is why you need to escape it:

- \# Heading

Nesting tables in lists

As stated below, Tables are not really covered by CommonMark, hence this is an idiosyncracy of our own parser.

You can nest tables in lists in both Markdown and CommonMark:

- Item

    | head1 | head2 |
    | -------- | ------- |
    |cell A    | cell2 A |

However, this particular case is going to adhere an empty first column in CommonMark.

You can solve by any of the following edits:

  • Indent with two spaces instead four
- Item

  | head1 | head2 |
  | -------- | ------- |
  |cell A    | cell2 A |
  • Remove the optional pipes
- Item

    head1 | head2
    -------- | -------
    cell A    | cell2 A

Deviations from CommonMark standard

CommonMark defines an easy way to DRY links using references syntax. If used in API Description Document, there currently are constraint on its usage.

FORMAT: 1A

# API Blueprint with Reference Links

### List resource [GET /resource]

[link-example]: http://example.com

This [Reference links][link-example] renders fine.

+ Response 204


### List different resource [GET /another-resource]


This [Reference][link-example] has some issues.

+ Response 204

Apiary currently parses Description blocks (i.e. Introduction or Request description) as a separate document. Hence, reference links works within the same context, but unfortunately doesn’t work accross different ones.

To mitigate the issue, you currently need to copy the reference link into every block or to use standard link syntax.

Extensions to CommonMark standard

While CommonMark is a great new standard, it intentionally doesn’t cover some of the common usages. Those are provided via extensions, and some of them are enabled in Apiary.

Tables

Table are supported only in their HTML form in CommonMark. However, they are enabled in Apiary as an extension.

See GitHub Help for more information on syntax.

Related topics