Escaping Characters
Writing about Markdown is a strange job, because the document you are writing is Markdown. A book title that needs asterisks around it, a shell prompt that starts with a hash, a Windows path full of backslashes — every one of them looks like syntax to the parser, and every one of them gets eaten if you do nothing. The fix is a single character: put a backslash in front of it and the parser treats it as ordinary text.
That fix sounds trivial, and in the common case it is. But escaping has edges that catch people out, and the edges are where the real damage happens. A backslash escapes exactly one character, not a whole word. It only works on punctuation, so a backslash before a letter does nothing except stay on the page. And — this is the rule most often stated backwards — inside code you must not escape at all, because code is not parsed in the first place. This page walks through what a backslash can escape, what it cannot, how to escape a backslash itself, what happens when you forget, and the one place where a different escape character is needed: the pipe inside a table cell.
CommonMark lets a backslash escape any ASCII punctuation character — the whole punctuation row of a keyboard, from the exclamation mark to the tilde. You do not need to memorize the list. In practice you escape the characters that Markdown gives a meaning to: the asterisk and the underscore that open emphasis, the hash that opens a heading, the backtick that opens code, the square brackets that open a link, the pipe that ends a table cell, and the characters that can open a line, such as the dash and the greater-than sign. The rule you will use most is the same one you already know from other languages: put the backslash immediately in front of the character.
\*does not become emphasis\*
\`does not become code\`<p>*does not become emphasis*</p>
<p>`does not become code`</p>Read the HTML output carefully, because it is the whole lesson. Each escaped character comes out of the renderer as the literal character, with no tag wrapped around it. The asterisk is a character in a paragraph, not the start of an <em> element, and the backtick is a character, not the start of a <code> span. Nothing was lost and nothing was added: the escaped form and the plain form produce the same visible text, which is exactly what you want.
The backslash does not escape “the rest of the word” or “the rest of the line”. It protects the single character that comes immediately after it, and then it is done:
\*a\*b<p>*a*b</p>The first asterisk is escaped and appears as a literal *. The second one is escaped too, so it also appears literally. The a and b in between are ordinary text, and no emphasis is formed anywhere, because both delimiters were neutralized before the parser ever looked for a pair.
Contrast that with the unescaped version. Two asterisks with no space around them are a valid emphasis delimiter, and the parser will happily take the text between them:
2*3*4<p>2<em>3</em>4</p>The 3 has been wrapped in an <em> element and the multiplication sign is gone from the page. This is the shape of the failure that escaping exists to prevent: not an error message, but content quietly reformatted or swallowed. Note that 2 * 3 * 4, with spaces around the asterisks, is not emphasis — a delimiter that is surrounded by whitespace can neither open nor close emphasis — so the same document can look correct in one place and broken in another. Escape anything that might be read as a delimiter, whatever the surrounding spacing looks like today.
A backslash escapes punctuation. It does nothing to a letter or a digit, and the backslash itself stays on the page:
\a plain backslash<p>\a plain backslash</p>That rule has a useful corollary, because it saves you from doing work you do not need to do. A backslash in front of a letter is not an escape, so the letter after it is unaffected — and the backslash was never going to be treated as syntax anyway. That means Windows paths need no escaping at all:
The path is C:\Users\demo.<p>The path is C:\Users\demo.</p>Every backslash in C:\Users\demo is followed by a letter, so each one is just a backslash. The path survives a round trip through the renderer unchanged. If you have ever seen a Windows path appear with doubled backslashes on a web page, the cause is almost always that someone escaped it anyway.
To display one backslash, you have to escape it, and because the backslash is itself punctuation, escaping it means writing two:
C:\\Users\\test<p>C:\Users\test</p>The first backslash escapes the second one, and the pair collapses into a single literal backslash. This is the only place where doubling is the right move, and it is worth internalizing the asymmetry: C:\Users needs no escaping, C:\\Users displays as C:\Users, and C:\Users inside a code span needs no escaping either — which brings us to the rule people get backwards most often.
Some characters only mean something at the beginning of a line. A dash starts a bullet, a digit followed by a dot starts an ordered list, a greater-than sign starts a blockquote, a hash starts a heading. Escaping them turns them back into ordinary text:
\- not a list
1\. not an ordered list
\> not a blockquote
\# not a heading
# A heading you did not escape<p>- not a list
1. not an ordered list
> not a blockquote</p>
<p># not a heading</p>
<h1>A heading you did not escape</h1>The first three lines collapse into a single paragraph, because none of them is a block marker any more, and the escaped hash stays a paragraph as well. The last line is the failure mode: a hash and a space at the start of a line is a heading, and the renderer turns the rest of the line into an <h1> element. One detail worth remembering, because it trips up people who assume the hash always wins: CommonMark requires a space between the hash and the text. #Heading is not a heading at all — it is a paragraph that happens to start with a hash — while # Heading is an <h1>. Either way, the safe move on a line you do not want promoted to a heading is to escape the hash.
Inline code and code blocks are not parsed. That is the whole point of them: they are the escape hatch of Markdown itself. Inside a code span or a code block, a backslash is just a backslash and the character after it is just a character:
`\*not em\*`<p><code>\*not em\*</code></p>Both the backslashes and the asterisks are on the page, exactly as they were typed. Nothing was escaped, because nothing needed to be. If you want to show Markdown syntax, you put it in code and you write it the way you would type it, with no backslashes at all. The same holds for a fenced code block: the content of a fence is copied byte for byte into the output, which is why this page can show you raw Markdown without any of it turning into real headings and emphasis.
A table cell ends at the next pipe character, so the pipe is the one character that needs a different treatment. Inside a table cell you escape it with a backslash, and the pipe then survives as part of the cell content:
| Expression | Meaning |
|:---|:---|
| `a \| b` | a pipe inside a table cell |The cell a \| b renders as the code span a | b, and the table keeps its two columns. The rule is specific to tables: the same backslash inside an ordinary paragraph would be consumed as an escape and the pipe would appear without it. If you are writing mathematical notation, an absolute value written with plain pipes will break the table, so write it as $\lvert A\rvert$ instead.
| Written as | Actually renders as | Why |
|---|---|---|
\a | \a | only punctuation can be escaped |
C:\Users\demo | C:\Users\demo | the backslash is followed by a letter |
C:\\Users\\test | C:\Users\test | a doubled backslash collapses into one |
2*3*4 | 2 with 3 in italics | an unescaped asterisk pair becomes emphasis |
`\*not em\*` | \*not em\* | nothing inside code is parsed |
The rule “no escaping is needed inside code” is really “no escaping is allowed inside code”. Writing \* in a code span puts a literal backslash on the screen next to the asterisk, and the reader sees a character that is not part of the code they were meant to read. The two mistakes are symmetric: escaping prose you did not need to escape, and failing to escape prose you did. The giveaway for the second is a heading that is not a heading, or a pair of words that have been turned into italics without anyone asking for it.
Rewrite the following passage as Markdown. Requirements: the asterisks around the book title must appear literally rather than turning into italics; the hash at the start of the second line must not become a heading; the Windows path must survive unchanged; and the asterisk in the last sentence must sit inside inline code with no escaping at all.
*Learning Everything* is a book worth reading.
# Not a heading
The path is C:\Users\demo.
The asterisk in the last sentence stays literal: *star*Approach:
The three symbols need three different treatments, which is the point of the exercise. The asterisks and the hash are Markdown syntax characters, so they need a backslash in front to become ordinary text. The path needs nothing at all, because a backslash in front of a letter is not an escape and never was. The last asterisk goes inside inline code, where nothing is parsed, so escaping it would leave a stray backslash on the page.
Steps:
- Put a backslash in front of each of the two asterisks around the book title, writing
\*Learning Everything\*. The rendered result is a literal pair of asterisks with no italics. - Put a backslash in front of the hash on the second line, writing
\# Not a heading. It is now an ordinary paragraph, not a heading. - Leave the path exactly as it is, writing
C:\Users\demo. Each backslash is followed by a letter, so no escape is created and nothing changes. - Wrap the asterisks of the last word in inline code, writing
`*star*`. Code is not parsed, so it needs no escape and gains no backslash. Check the result: the asterisks and the hash are literal characters, the path is unchanged, and the code span shows a bare asterisk.
Answer:
\*Learning Everything\* is a book worth reading.
\# Not a heading
The path is C:\Users\demo.
The asterisk in the last sentence must not be escaped: `*star*`You can now say which characters a backslash can escape, that it protects exactly one character at a time, and that it does nothing in front of a letter — which is why Windows paths need no escaping. You can write the doubled backslash that displays a single one, and you can escape the line-start markers so a bullet or a heading stays plain text. Most importantly you know that inside code nothing is parsed, so escaping there only adds a backslash the reader did not ask for. From here on, whenever a character in your prose looks like syntax, reach for the backslash — and when the character is already inside code, reach for nothing at all.