Markdown cheatsheet · Escaping characters
Escaping characters in markdown
A backslash before a markdown character prints it instead of formatting. It works on punctuation only, and for anything longer than a character or two, a code span is the better tool.
The syntax
Put a backslash in front of a markdown character and it prints literally instead of formatting.
\*not italic\* \# not a heading 5 \* 3 = 15
*not italic*
# not a heading
5 * 3 = 15
The characters you can escape
CommonMark lets you escape any ASCII punctuation character. These are the ones that actually mean something in markdown, so these are the ones worth escaping:
| Character | Escape | What it does unescaped |
|---|---|---|
\ | \\ | Escapes the next character |
` | \` | Starts inline code |
* | \* | Bold, italic, list bullet, rule |
_ | \_ | Bold, italic |
{ } | \{ \} | Attributes, in some flavors |
[ ] | \[ \] | Links, footnotes, wikilinks |
( ) | \( \) | Link targets |
# | \# | Heading |
+ - | \+ \- | List bullet, rule, front matter |
. | 1\. | Ordered list, after a number |
! | \! | Image, before a bracket |
| | \| | Column break, inside a table |
< | \< | Opens an HTML tag or autolink |
A backslash before a letter is not an escape: \d renders as a literal backslash-d, which is why regular expressions survive markdown better than you'd expect. Escaping only applies to punctuation.
The better answer: use code spans
Escaping character by character gets unreadable fast. Inside backticks, nothing is markdown, so nothing needs escaping.
Hard to read: \*\*not bold\*\* Easy to read: `**not bold**`
Hard to read: **not bold**
Easy to read: **not bold**
The tradeoff is that a code span looks like code: monospaced and usually tinted. If you're showing syntax, that's exactly right. If you just want a literal asterisk in a sentence, escape it.
Escaping a backtick inside code
You can't escape a backtick with a backslash inside a code span, because backslashes aren't special in there either. The trick is to use more backticks on the outside than on the inside.
`` the `code` word ``
the `code` word
A space just inside the outer backticks is stripped, which is what lets a snippet start or end with a backtick. For whole blocks, use four backticks around a three-backtick fence.
The cases that trip people up
A pipe inside a table cell
A literal | starts a new column. \| escapes it. Inside a code span in a table, the backslash sometimes doesn't take, and the HTML entity | is the fallback that always works.
Underscores in the middle of a word
Most renderers, GitHub included, already ignore _ inside a word, so snake_case_name is usually safe without escaping. "Usually" is doing real work in that sentence: older renderers italicise it. If the text matters, use a code span.
A number followed by a period at the start of a line
Writing 1986. What a year. gives you a list starting at 1986. Escape the period: 1986\. What a year.
Angle brackets
<something> may be swallowed as an HTML tag. Escape the opening bracket, or use a code span, or write the entity <.
A hash at the start of a line
#1 in sales becomes a heading. \#1 in sales doesn't.
Common questions
Can I escape inside a code block?
No, and you don't need to. Everything inside a fence is literal, backslashes included.
Why doesn't \* work in my renderer?
Check you're not already inside a code span or fence, where the backslash prints itself. If you're in a table cell, try the HTML entity instead.
Do HTML entities work as an alternative?
Where HTML is allowed, yes: * is an asterisk and | is a pipe. They're uglier but they get through renderers that mangle backslashes.