Beyond Markdown


1. Emphasis

No personal strong opinion. Will follow best consensus/practices.

2. Reference links

No personal strong opinion. Will follow best consensus/practices.

3. Indented code blocks and lists

+1.0 with your fix.

4. Raw HTML


+1.0 with your fix


+0.5 with your fix

  • should be completed with a section ::: too, like with pandoc fenced_div.
  • which should now rather be understood as a section marker compatible with html5 section, article, main etc.

5. Lists and blank lines

No personal strong opinion. Will follow best consensus/practices.

6. Attributes

+1.0 with your fix. A very good work.


  • {.class} should be recognized too
  • Attributes at end rather than at begin have appeared here and there.
    Why not relax conditions about these.

Edited: This link on github go in this direction too : generic directive extension list

1 Like


An alternate fix for emphasis:

Require an exact match between the opening and closing delimiters. Kind of like inline code spans.

Emphasis would begin with a left-flanking delimiter run of exactly 1, 2, or 3 asterisks or 1, 2, or 3 underscores, and end with a right-flanking delimiter run of exactly the same length and character.


**strong emphasis**
__strong emphasis__

***strong plus regular emphasis***
___strong plus regular emphasis___

Four or more sequential asterisks or underscores would render literally.

****no emphasis****
____no emphasis____

Unmatched delimiter runs would not create emphasis at all, and could not divide into emphasis plus literal characters.

**no emphasis*

**no emphasis***

_no emphasis*

Any unmatched delimiters, including within emphasis, would render literally.

**asterisk* within strong emphasis**
__underscore_ within strong emphasis__

*asterisks** within emphasis*
_underscores__ within emphasis_

To create a literal asterisk or underscore next to emphasized text, a character can be escaped…

*asterisk\** inside emphasized text

*asterisk*\* outside emphasized text

…or a different delimiter character can be used.

_asterisk*_ inside emphasized text

_asterisk_* outside emphasized text

Nested emphasis would work.

**strong and *emphasis* within strong**

It would also be possible to nest the same type of emphasis by alternating asterisks and underscores.

*lots _of *emphasized* text_ here*

When using asterisks in a single word, emphasis would start with a left-flanking or both-flanking delimiter run, and end with a both-flanking or right-flanking delimiter run. This would allow intraword emphasis.


These rules should be pretty intuitive and easy to learn, and backwards compatible to a large extent.

And they eliminate a huge amount of complexity and ambiguity.



I think @aoudad’s suggestions on emphasis are sound, keeping both ease of reading and backward compatibility. On the rest, I tend to agree with @jgm. However, the bit that I find toughest to get behind is getting rid of shortcut reference links. Those are not only convenient, but are very readable as well. [foo][] gives up a bit of that human-readability for parsing convenience.

At any rate, looking forward to CommonMark 1.0.



Some thoughts…

  1. Emphasis

    I like using _emphasis_ and *strong emphasis*. As somebody mentioned already, that’s how it works on WhatsApp, Facebook, and Slack, and it seems very logical. They also support ~strikethrough~, `monospaced`, and triple-backtick code blocks, which are all nice.

    I personally don’t care much for intra-word emphasis and I’d rather keep the single tilde free for strikethrough syntax.

  2. Reference links

    Shortcut reference links are great, and it would be a shame to remove them. They are very intuitive and readable. Just go to a random Hacker News comment thread and you’ll see people instinctively using them, even though they’re not supported there (just Ctrl/Cmd+F [1] to see examples).

    They are also essential for wiki-style and academic writing, which are both extremely rich in references. The extra noise caused by [this style][] would hurt readability.

  3. Indented code blocks

    Big yes to the more logical list indentation style, and to removing indented code blocks. What a pain they are.

  4. Raw HTML

    Not a fan of the specific syntax (why the extra =?), but this sounds good in general.

  5. Lists and blank lines

    I’d rather we just allow the creation of a list even without a blank line separating it from a paragraph. It seems to me this would rarely be a problem in practice. The example given can just be fixed by having 220. be on the previous line. Or maybe one could allow escaping the period like so 200\. to mean that you really do want to write 200. at the beginning of the line, and not start a list. Again, I really doubt this will happen very often.

  6. Attributes

    Why not use a consistent way of creating attributes for headers, like on GitHub? This would avoid having to introduce extra syntax, and keep documents cleaner.



There is a discussion regarding adding header IDs to CommonMark, but it seems that - at least in some cases - having the ability to manually specify these is useful.



To keep shortcut reference links readable, how about double brackets?

In other words, links would use external brackets for a reference label [foo][bar], and nested brackets if the link text is its own label [[foo]].

That makes it immediately clear there’s a link, not just a span or literal brackets; and it’s more natural-looking than appending empty brackets [foo][].


<a href="">foo</a>

If there’s no link reference definition, the double-bracketed text would still be a link. It could fall back to an implicit page link:

<a href="foo">foo</a>


That’s a good suggestion. This is similar to the [[text]] format of the Wiki markup used by MediaWiki, and it is human-readable and doesn’t look horrid.

The trouble would be that it isn’t backward-compatible. But it is something I feel one can support, since I feel standardization is more important than backward-compatibility.



I would say MediaWiki is exactly the reason why IMHO Markdown (or derivatives of it) should not use [[foo]] for the ordinary links. Wiki is one very natural application for Markdown-like syntax and it’s therefore better to reserve that syntax for wiki-links to other articles defined by the database of its articles; not to some arbitrary URIs.




6. Attributes

+1.0 with your fix. A very good work.


  • {.class} should be recognized too
  • Attributes at end rather than at begin have appeared here and there.
    Why not relax conditions about these.

See Also