Markdown Ate the Underscores in __init__: The Everyday Text That Turns Into Formatting, and the Backslash That Stops It

When Markdown sees two underscores flanking a word, asterisks wrapped around digits, or a pound sign alone at a line's start, it turns that text into formatting — not content. A backslash placed immediately before any of those characters tells CommonMark-compatible renderers to treat the character as literal. Inside code spans, the backslash is not enough: change the delimiter instead.

Why Markdown Eats Ordinary Text

Seven Stack Overflow questions on the escape, backslash, and underscore axis have accumulated 385,297 combined views as of November 2026 — the top question ("how to show underscores symbol in markdown?") alone has 177,278 views.¹ That demand is structural, not accidental.

The underlying cause: Markdown was designed for prose. Its author, John Gruber, envisioned users wrapping *asterisks* around words they wanted emphasized and typing # to signal headings.² The format was not designed with software identifiers in mind. A 2024 study of 31,169,429 Stack Overflow answers found that 38.5% of answers contain code formatting, and in 63.5% of those cases the code formatting is used to highlight identifiers rather than runnable code.³ Code notation became the dominant practical use of Markdown escaping — not Gruber's prose emphasis.

The collision point: underscores. A study of 135 developers (Binkley et al., ICPC 2009) found that underscores and camelCase are the two most common conventions for multi-word identifiers.⁴ Write __init__, my_var, or obj.__dict__ in a plain note and Markdown interprets the underscores as emphasis delimiters.

The CommonMark specification extended Markdown's escaping to cover any ASCII punctuation character.⁵ But three major renderers — Python-Markdown, pandoc's markdown_strict reader, and the original Markdown.pl — still recognize only Gruber's original list of 15–16 characters. And pandoc's default markdown reader adds a trap of its own: a backslash before an uppercase letter may be parsed as a raw TeX command and silently deleted from HTML output. The behavior is engine-dependent, and the safe path depends on which renderer processes your notes.

The Trap Table: Everyday Text That Becomes Formatting

The table below covers ten tested setups: commonmark.js 0.31.2, markdown-it 14.1.0 (CommonMark and GFM modes), micromark 4.0.1 with GFM extension, Python-Markdown 3.11.3 (default), and pandoc 3.13 (four readers: markdown, gfm, markdown_strict, commonmark), plus Markdown.pl 1.0.1.⁶ "Universal fix" means it works in all ten. A code span wraps text in backticks and produces <code> output — the safest option when you need the text literal but want monospace rendering. Use \_ or \* escapes when you need the text in a prose font.

Note on \$, \~, \|, \", \=, \@, \<: In Python-Markdown (default), pandoc markdown_strict, and Markdown.pl, a backslash before these characters is not treated as an escape — the backslash appears literally in output. These characters are not in Gruber's original escapable list (see §Origins below). If your notes are processed by one of those engines, use a code span for portable safety.

Where Backslash Falls Short: Engine Exceptions

The CommonMark specification states: "Escaped characters are treated as regular characters and do not have their usual Markdown meanings."⁵ That rule holds cleanly in CommonMark and GFM renderers. Three common engines narrow it.

Python-Markdown, pandoc markdown_strict, and Markdown.pl recognize only the characters in Gruber's original list: \ `` * _ { } [ ] ( ) # + - . ! (Markdown.pl source L53 carries 16 entries; Python-Markdown 3.11.2 ESCAPED_CHARS adds >, also reaching 16).^{9 10} Write \$ in a MkDocs project (Python-Markdown engine) and the output contains a visible backslash before the dollar sign — the backslash was not consumed as an escape character.

Pandoc markdown (the default reader) adds a separate trap. Its documentation explains that inline TeX commands are preserved and passed unchanged to LaTeX and ConTeXt writers.¹¹ In practice, this means C:\Users\name is parsed as C: followed by the TeX command \Users, which produces an empty string in HTML output. The path C:\Users\name becomes C: in the rendered page — with no warning, no error, no hint that anything was deleted. The same logic swallows Use \n for newlines → Use for newlines. A code span is the only protection: `C:\Users\name` passes through every tested renderer untouched.

The hashtag trap is engine-specific. CommonMark and GFM require a space after # for a heading — #meeting is not a heading in those renderers. Python-Markdown, pandoc markdown_strict, and Markdown.pl do not require the space: #meeting notes becomes <h1>meeting notes</h1>. RFC 7764, the IETF informational memo on Markdown variants, identifies "Multiple underscores in words" as the first documented difference between GitHub Flavored Markdown and original Markdown¹² — but the no-space heading difference is equally consequential for anyone pasting hashtag-style labels into a renderer they did not choose.

Inside Code Spans, the Backslash Is Not Enough

Inside a code span or a fenced code block, CommonMark §2.4 is explicit: "Backslashes before other characters are treated as literal backslashes."⁵ A \* inside backticks stays as \* — the backslash is not consumed as an escape. To embed a backtick inside a code span, the solution is to change the delimiter to a longer backtick run, not to escape anything. The full mechanics — including unclosed-fence hazards and engine-specific edge cases — are covered by ["How to Put a Backtick Inside Code in Markdown"][#538].¹³

If you paste Markdown notes into Slack, Teams, or Telegram, escaping may behave differently from any renderer in the table above. Those apps implement their own dialect parsers. The divergence is covered by ["Paste a Markdown Note Into Slack, Teams, or Telegram and Your Italics Turn Bold"][#558].¹⁴

How the Escapable Character List Grew

John Gruber's original Markdown syntax page lists: \ `` * _ { } [ ] ( ) # + - . ! — fifteen character tokens, with backslash itself making a self-escape possible.² The source of Markdown.pl 1.0.1 carries sixteen entries in its escape_table hash (> added).⁹

The CommonMark project, which began formalizing Markdown's rules in 2014, extended escaping to cover any ASCII punctuation character — a larger set, 32 characters in the ASCII punctuation block. That is the basis for the "any ASCII punctuation" language in GitHub's documentation: "You can tell GitHub to ignore (or escape) Markdown formatting by using \ before the Markdown character."¹⁵

CommonMark extended Gruber's list; it did not replace the core logic. A backslash before any character outside the extended set is still treated as a literal backslash — not discarded, not consumed. The full current list, with examples, is covered by [the MNMNOTE Markdown cheat sheet][#01] §Escape characters.¹⁶

Frequently Asked Questions

How do I write __init__ in Markdown without it turning bold?

Wrap it in backticks: `__init__`. That produces <code>__init__</code> — monospace, unambiguous, safe in every tested renderer. If you need the text in a prose font, escape both pairs of underscores: \_\_init\_\_. The backslash approach works in CommonMark, GFM, and pandoc, but the code span is portable everywhere.

Why is my Markdown backslash escape not working?

Three likely causes. First, your renderer may be Python-Markdown, pandoc markdown_strict, or Markdown.pl — those engines only recognize Gruber's original 15–16 characters, so \$ or \~ leaves a visible backslash in output. Second, you may be inside a code span or code block, where backslashes are literal by definition. Third, pandoc's default markdown reader may be treating your backslash as a TeX command prefix rather than an escape. A code span resolves all three cases.

How do I escape asterisks in Markdown?

Place a backslash immediately before each asterisk: 2\*3\*4 renders as 2*3*4. If the asterisks are part of a longer pattern you want preserved exactly — a glob, a pointer in pseudocode — a code span is cleaner: `2*3*4`. Both approaches work in CommonMark and GFM renderers.

How do I write a Windows file path in Markdown?

Use a code span: `C:\Users\name\Documents`. Do not rely on a backslash escape for Windows paths — pandoc's default markdown reader interprets \U, \D, and similar sequences as raw TeX inline commands and silently removes them from HTML output. The code span passes through all ten tested renderers unchanged.

How do I escape a hashtag at the start of a line in Markdown?

Prefix it with a backslash: \#meeting notes. In CommonMark and GFM, a # without a trailing space is not a heading, so \# is redundant but harmless. In Python-Markdown, pandoc markdown_strict, and Markdown.pl — which create headings from #tag without a space — \# is the escape that prevents the heading. Since # is in Gruber's original escapable list, \# works in all ten tested engines.

Does backslash escaping work inside a code block or fenced block?

No. The CommonMark specification states that inside code spans and code blocks, "Backslashes before other characters are treated as literal backslashes."⁵ The backslash appears in the output unchanged — it escapes nothing. For the technique of placing a backtick inside a code span, see ["How to Put a Backtick Inside Code in Markdown"][#538].¹³

What is the safest single rule to remember?

Use a code span for anything you want to survive every renderer verbatim — identifiers, paths, math expressions, shell syntax. Use a backslash escape for one-off inline prose fixes when you are on a CommonMark or GFM engine and you need the text in a prose font. Never rely on a backslash inside code spans or code blocks, and never rely on \$, \~, or other non-Gruber characters in Python-Markdown or markdown_strict environments.

The trap is not that Markdown is broken — it is that Markdown was designed for prose and inherited those defaults intact. A backslash is a reliable signal to any CommonMark-compatible renderer. A code span is a reliable signal to every renderer. Text that matters: use one of the two.

MNMNOTE stores your notes locally on your own device as plain Markdown files. Backslash escapes in your writing are yours to keep. mnmnote.com