Markdown Syntax Quirks That Trip Up Beginners (and How Renderers Differ)

By Elena Marsh · September 18, 2026 · Writing

Markdown looks like plain text with a few symbols, but the spec has sharp edges: nested lists, indented code, line breaks and tables all behave differently across renderers.

Markdown sells itself on simplicity: a few symbols turn plain text into structured HTML. That promise holds for paragraphs, headings and emphasis. The moment you nest lists, indent code blocks, mix ordered and unordered items, or rely on a line break behaving a certain way, the simplicity frays, and the same source can produce visibly different HTML depending on which renderer processes it.

This guide walks through the quirks that catch beginners most often, explains why they happen, and shows how to write Markdown that converts predictably no matter where it lands.

In this article:

Why Markdown is not one language

The original Markdown specification was deliberately ambiguous in places, and the ecosystem responded by producing several variants. GitHub Flavored Markdown adds tables, task lists and strikethrough. CommonMark is a strict, testable specification of the core syntax. Many platforms layer their own extensions on top. The result is that "valid Markdown" is a relative term, and a document that renders perfectly in one place may look broken in another.

The quirks that catch beginners

Nested lists need precise indentation

A nested list item must be indented to align with the text of its parent, not the marker. For an unordered list using a hyphen, that means indenting the child by two spaces. Indent by four and some renderers treat it as a code block inside the list; indent by three and behaviour varies. The safe rule is to use two spaces for unordered nesting and four for ordered lists that use a dot, then test.

Two spaces or a backslash make a line break

A single newline within a paragraph does not create a line break in most renderers; it produces a soft wrap that the browser ignores. To force a hard break you either end the line with two spaces or a backslash, or leave a blank line to start a new paragraph. This is the quirk that makes pasted addresses and poems collapse into a single run of text.

Indented code blocks conflict with nested lists

Four leading spaces traditionally mark a code block, but inside a list those same four spaces are how you nest content. The collision means an indented code block inside a list item often fails to render as code. Fenced code blocks, using three backticks, avoid the ambiguity entirely and are the safer choice.

Emphasis boundaries are greedy and surprising

Surrounding text with asterisks or underscores produces emphasis, but the rules about where emphasis starts and stops are subtle. Underscores in the middle of a word, like "snake_case_var", do not trigger emphasis because they are adjacent to word characters. Asterisks do. This is why "file_name" renders intact but "file*name" italicises unexpectedly.

How renderers differ in practice

Tables are the clearest example. Original Markdown has no table syntax; GitHub Flavored Markdown and most modern renderers do. A table written in a renderer that lacks support appears as a row of pipes and dashes in the output. Task list checkboxes, strikethrough with tildes, and autolinking of bare URLs are similarly extension dependent. If your document will travel between systems, stick to the core syntax for anything that must render, and treat extensions as progressive enhancement.

Worked examples of tricky input

Example one: a nested task list

A parent task with two indented subtasks requires the subtasks indented by two spaces and aligned under the parent text. Write the parent as "- [ ] Plan the release", then on the next line two spaces followed by "- [ ] Draft notes", and two spaces followed by "- [ ] Tag the build". Misalign by one space and the subtasks detach from the parent and become a separate top level list.

Example two: code inside a list

To place a code block inside a list item, use a fenced block indented to align with the item text. A list item "- Install the package:" followed by a line indented two spaces and beginning with three backticks, then the code, then three closing backticks, renders the code as a block belonging to that item. Using four space indentation instead often breaks the list.

Example three: a line break in an address

Writing an address on separate lines with single newlines collapses it into one paragraph. End each line with two trailing spaces, or a backslash, to preserve the breaks. Alternatively, end each line with a double space and the renderer inserts the HTML break element, keeping the address on its own visual lines.

Common mistakes

FAQ: Markdown edge cases

Why does my list render as a single paragraph?

There is no blank line between the preceding paragraph and the list. Insert one and the list will be recognised. Lists also need their items separated correctly: consecutive items at the same level do not always need blank lines between them, but a paragraph inside a list item does.

Should I use asterisks or underscores for emphasis?

Asterisks are more predictable because they work at word boundaries, while underscores are ignored mid word. Use asterisks unless you have a specific reason to prefer underscores.

How do I show a literal asterisk or underscore?

Escape it with a backslash. "\*" renders as a literal asterisk and "\_" as a literal underscore. This is how you write about Markdown syntax in Markdown.

Wrapping up

Markdown is simple at the surface and fiddly in the corners. Use fenced code blocks, two space nesting, explicit line breaks, and asterisks for emphasis, and your documents will convert predictably across the renderers that matter. When in doubt, convert and inspect the HTML rather than guessing.

Convert your Markdown to clean HTML and inspect the result instantly.

Try the Markdown to HTML tool.

SwiftMultiTool — free online tools for everyone. Home · Blog · About · FAQ · Contact