Inline parsing has formal rules for delimiter runs, link boundaries, and escape handling.
Inline parsing is not decoration
Inline Markdown is sometimes described as simple formatting: emphasis, strong emphasis, code, links, and images. That description is useful for beginners, but it hides the complexity that parsers must handle. Inline parsing is a formal process that scans text inside paragraph-like blocks and identifies delimiters, literal text, code spans, escapes, entity references, links, images, and emphasis structures.
The difficulty comes from Markdown’s readability goal. The same punctuation characters used for formatting are also normal writing characters. Asterisks appear in prose. Underscores appear in identifiers. Brackets appear in text. Backticks appear in documentation about Markdown itself. The parser must decide when punctuation is syntax and when it is literal content.
CommonMark handles this with precise rules for delimiter runs and precedence. A delimiter run is a sequence of characters such as * or _ that may open or close emphasis depending on surrounding characters. These rules are more complex than “put asterisks around a word.” They account for punctuation, whitespace, intraword emphasis, and nesting.
Emphasis and strong emphasis
Emphasis is usually written with one * or _, and strong emphasis with two. Combined emphasis can use three markers. But parser behavior depends on whether delimiters can open, close, or both. For example, underscores inside words are treated carefully because many programming identifiers contain underscores. Without these rules, Markdown could accidentally italicize parts of variable names.
Asterisks are generally safer for emphasis in technical writing because they create fewer intraword surprises. Many style guides recommend *italic* and **bold** instead of underscore equivalents. This is not because underscores are invalid, but because asterisks are more portable across dialects and easier to reason about in prose containing identifiers.
Nested emphasis should be used sparingly. While CommonMark defines behavior precisely, deeply nested emphasis reduces readability in source and output. If a sentence needs heavy emphasis nesting, rewrite it. Markdown’s strength is readable source, not typographic complexity.
Escaping punctuation
Backslash escapes allow authors to force punctuation to be literal. If a line starts with a number and period but should not be an ordered list, escape the period. If asterisks should be visible, escape them. If a heading marker should be literal, escape the hash.
CommonMark allows backslash escaping for ASCII punctuation. Escapes do not work the same way inside code spans and code blocks because those contexts already treat content literally. This is a common beginner mistake: adding backslashes inside code examples when they are unnecessary.
Escaping is useful, but over-escaping makes source harder to read. A good style guide should teach when escaping is necessary rather than encouraging defensive escaping everywhere. If a character is not syntactically active in context, leave it alone.
Entity and numeric character references
Markdown supports HTML entity references such as & and numeric references such as # in many inline contexts. These references are interpreted as characters in rendered output, except in code spans and code blocks where they remain literal. This behavior allows authors to write characters that might otherwise be difficult to type or could conflict with syntax.
However, entity references do not replace structural syntax. For example, using an entity for an asterisk does not create emphasis. The parser recognizes structure from source characters, not from characters produced after entity decoding. This distinction is important for formal semantics.
In most modern Markdown documents, write Unicode characters directly when possible. Use entities when they improve compatibility, avoid ambiguity, or are required by surrounding HTML. For technical examples, prefer literal source inside code spans so readers see exactly what to type.
Code spans as inline escape zones
Code spans are often the cleanest way to show syntax. Instead of escaping every punctuation character, wrap the token in backticks. This is ideal for filenames, commands, identifiers, media types, HTML tags, and Markdown examples.
For example, writing about # Heading inside prose is clearer as inline code than as escaped text. The code span tells both parser and reader that the content is literal. It also improves visual scanning in rendered documentation.
Inline links and precedence
Links and images interact with inline parsing because they use brackets, parentheses, and optional titles. A parser must distinguish ordinary bracketed text from link text, reference labels, images, and nested inline content. Code spans and escapes can prevent link parsing when needed.
This means inline semantics are not isolated features. Emphasis can appear inside link text. Code can appear inside link text. Escaped brackets can prevent link recognition. Reference definitions collected during block parsing can affect inline link resolution. The inline parser is a coordinated system.
Practical authoring rules
Use inline code for exact syntax, identifiers, filenames, and commands. Use asterisks for emphasis unless your project has a different convention. Escape punctuation only when it would otherwise be parsed as syntax. Avoid dense nesting of links, emphasis, and code because it harms source readability. If you need to explain Markdown syntax itself, prefer code spans and fenced examples over repeated escaping.
These rules make documents easier for both humans and parsers. They also reduce malformed links, accidental emphasis, and literal punctuation bugs that change visible text. Inline syntax is small, but it sits inside nearly every paragraph, so consistency compounds across a documentation site. The same principles continue in Markdown links and reference definitions, where inline parsing determines whether bracketed text becomes a link or remains literal prose.
FAQ
Why does emphasis sometimes fail in Markdown?
Emphasis depends on delimiter rules, surrounding whitespace, punctuation, and whether markers can open or close. It is not only a matter of matching characters.
Are asterisks better than underscores?
For technical writing, asterisks are often safer because underscores appear in identifiers and can create portability issues across dialects.
What characters can be escaped in Markdown?
CommonMark allows backslash escaping of ASCII punctuation characters in normal inline contexts.
Do escapes work inside code spans?
No. Code spans are already literal contexts, so backslashes remain part of the code content.
When should I use HTML entities?
Use entities when you need a specific character representation or must avoid ambiguity, but prefer direct Unicode or code spans for most modern documentation.
Related tutorials
- Use code spans as literal zones in Markdown Code Spans, Fenced Code Blocks, and Raw HTML.
- Continue with Markdown Links, Images, and Reference Definitions.
- Check inline behavior through CommonMark Test Suite and Dingus.
- Study delimiter implementation in Markdown Parser Implementation Theory.
- Represent inline nodes in Markdown AST with mdast.
Continue with Links, Images, and Reference Definitions.