Feedback collection / review

At the request of several co-workers, I drafted a review of Common Markdown (as of roughly 1.5 weeks ago) judging from the published spec. This was to cover what challenges / irritations we were likely to experience migrating from our current Markdown products & see if we should upgrade.

On reflection, this probably serves as a good discussion-starter for some parts of CommonMark. The below was written intended for an internal team discussion, so some coarse language is used. Please mentally adjust for missing diplomatic language; I can revise on request :smile:


News on the Common Markdown front.

The good:

A trailing slash (\) character can now generate a line break (<br />) as an alternative to two trailing spaces. No more literally-brainfuck syntax, and no sane-whitespace-on-save editor options interfering with documentation.

Speaking of the humble slash, it’s also a consistent way to MD-escape any non-whitespace character. # Header is a header, \# header is not (renders the hash), while both one \ two and one \\ two render a single slash.

Fenced code block info strings (where you add the language’s name after triple-backticks) are now defined to generate a class. As in <pre class="ruby"><code>. This is nice.

Creating line breaks in a list are now unambiguous and reasonable thanks to the trailing slash rule. This will render as expected, and makes it possible to write non-trivial lists:

1. Line\
Another line on first item
2. Second item

Tabs are unambiguously supported and equivalent to four spaces. Hooray for sanity:

* Item    
    * Sub-list via tab indentation
* Original list

The bad:

At the moment, HTML entities on the same line as a MD link causes the link to not render. Unsure if bug, will report.

They didn’t fix indented code blocks existing, and this is crippling for infinity reasons to the extent that parsers should definitely have a standards-breaking option to disable. This issue combined with differences from Github Flavored Markdown broke our command table from the documentation, for example.

There’s these link references that, while still one-pass, strike me as unnecessary parsing complexity. This feature may have “came along for the ride” from its predecessors. Not the end of the world.

Despite the below comment about explicit auto-linking, there are a whitelist of URI schemes which is short-sighted and unnecessary. Let’s whitelist the existence of Skype, AOL Instant Messenger, and… Unreal Tournament 2004. Common what are you doing. Common plz.

I really do not want an implicit list of all protocols that are allowed to exist until the end of time. I desperately hope this will be changed to allow any protocol that uses the link syntax.

The debatable:

URLs no longer auto-link without markup. http://example.com will not render a link, while <http://example.com> (or normal MD link syntax) will. Frankly, I’m on the fence as detecting a URL consistently is impossible and it is infuriating when normal next gets href’d.

Conclusion:

Overall, a solid improvement on the unusable insanity that is MarkDrown (ing in forks) on the wild web. I look forward to reducing vendor lock-in with regards to Bitbucket & Github having what amounts to entirely different languages for Readme.md rendering.

Libs exist in JS and C, use with maximum prejudice.


Hopefully this was useful! I’ll be around to answer any questions. Depending on reaction here, I might start a thread or two about the bits I feel most strongly about - there already is a thread on implicit code blocks, the biggest other issue would be the URI scheme whitelist.

1 Like

Thanks for the feedback; however, big collections of different points like this make it hard the forum organized. You might start a separate thread about the URI protocol whitelist issue, which seems a valid concern. Also, if you think there’s a bug involving entities and links, please report it on the github tracker.

Sounds good! I’ll create another thread on the URI protocol issue. That was the biggest point of concern.

No need, there’s already a topic about the URI whitelist.

2 Likes