Backticks all the way down

· Small Sharp Tools


Writing documentation about markdown means writing code spans that contain
backticks, which means counting.

The rule

A run of n backticks opens a code span, and it closes on the next run of
exactly n. So a single backtick inside a span needs a double-backtick fence:
` . Two backticks inside need three: `` .

Nothing is markup inside a span

Inside a span, *this* is asterisks, _that_ is underscores, [a](b) is a
link that never happens, and <b> is an angle bracket, a letter and another
angle bracket. That is the whole point of a span.

Padding

A span whose content begins or ends with a backtick needs a space of padding
so the fences do not run together. The space is part of the syntax, not the
content: `code` renders without the outer spaces.

Where it goes wrong

The failure mode is an unclosed run. `three ``` opens a run of one and
finds a run of three, which does not match, so the backtick stays literal text
and the rest of the paragraph reads normally. That is the behaviour you want:
a typo degrades to text, never to a swallowed paragraph.

In fences

Inside a fenced block none of this applies. A fence ends on a line whose first
non-space characters are the closing run, so a lone backtick in the middle of
a line is just a character:

$ echo "a ` b"
a ` b
markdown inline code
last updated: