First, a bit of history. Way back before github even existed, Michel Fortin (of PHP Markdown Extra) and I discussed the idea of a “fenced” or “delimited” code block syntax. We eventually decided on tildes as delimiters, and tildes as code fences are still supported in pandoc, PHP Markdown Extra, and many implementations. However, backtick fences, which were originally introduced by github, are now much more popular. (CommonMark currently supports both.)
I believe that backtick fences were conceived by analogy with Python multi-line strings, which are introduced by """
. The idea, roughly, is that if inline code quoting is done with `
, then multiline code quoting should be done with ```
.
But this is a false analogy. While Python (single-line) strings are always delimited by a single "
or '
character, in Markdown any number of backticks can be used to open and close inline code. If your code contains a single backtick, you can use double backticks to quote it. If it contains a double backtick too, you can use triple backticks. And so on. (It’s a bit more complex than this: you can use single backticks to quote text containing a double backtick, as long as it doesn’t contain a single backtick; the rule, which I notice this forum’s software does not follow, is that strings of exactly N contiguous backticks can quote code not containing any strings of exactly N contiguous backticks.)
The idea is really kind of ingenious: it avoids any need to escape characters in the quoted content. However, backtick code fences interfere with this system. Their presence makes it impossible to use a sequence of three or more backticks as an inline code delimiter when (a) the inline code starts at the beginning of a line and (b) it does not end on the same line. I think this is an ugly rough edge. Consider how unexpected the difference between these examples is:
` hello
this is inline code
`
`` hello
this is inline code with a backtick `
``
``` hello
this is NOT inline code with one backtick ` and two backticks ``;
it is a code block!
```
If you have a paragraph beginning with inline code that contains sequences of backticks with lengths 1 and 2, and it doesn’t fit on one line, then you’re completely out of luck; there is no way to write this in CommonMark. Of course, you could avoid the hard break and put everything on one line, but that is ugly and doesn’t usually have to be done.
Solutions?
-
Remove backtick code fences and just have tildes. This is just a stylistic difference, but I imagine the backtick style is so deeply entrenched that this would not be a popular option.
-
Put more constraints on the info string (e.g. require curly braces, as pandoc does, if you have anything more than a single word).
-
Others?
This was first brought to my attention by