Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Spec is unclear on how to tell apart fenced code block and code span #197
Per the spec, a fenced code block is started by a line that contains 0-3 spaces, 3 or more backticks, then 0+ non-backtick characters. It's ended by a line that contains 0-3 spaces and at least as many backticks as the start line.
This is ambiguous with code spans, which are simply any sequence of two equal-length backtick strings which contain one or more characters and don't contain an equal-length backtick string inside.
Since code spans can contain newlines, the following are valid code spans:
(Verified in the dingus, and the second even shows up as an example in the spec.)
But if you add one more backtick, you instead get a fenced code block:
(Sorry, GitHub's own implementation doesn't work properly here - it allows smaller numbers of backticks to close an open code block.)
The spec doesn't have any text detailing why this last case is one rather than the other.
This is actually a bit of a mess. Given that just about anything can be an info string (with the current spec), the current implementation effectively rules out any code span that begins with a string of three or more backticks and does not end with a closing backtick string on the same line.
So, for example, this does not get parsed as a code span:
even though this does:
(because backticks aren't allowed in info strings) and so does this:
Maybe the backtick code block syntax should be reconsidered, though it may be too widely established by now. The original fenced code block proposals discussed on markdown-discuss (long before github) used tildes, which didn't clash with the existing code span syntax. I'm sure github was seeing an analogy to python multiline strings -- which is appealing, but the analogy breaks down because code spans can begin with any number of backticks.
To restore sanity, we might disallow a line break right after opening backticks in a code span -- but that by itself wouldn't be enough, because of info strings.
I wonder if a discussion should be opened up on talk.commonmark.org?
By the way, I don't think the spec is actually ambiguous on this issue. "Indicators of block structure always take precedence over indicators of inline structure." See Example 3, for example. Your case is just another case of this type. But I think you have raised a good question about how rational/predictable the syntax is.