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
News on the Common Markdown front.
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
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.
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.
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
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.