Most Markdown problems are not exotic. The same handful of slips cause broken lists, text that runs together, and tables that refuse to appear. Here are the ten most common, with a fix for each.
1. No space after the #
#Heading is not a heading in CommonMark; it needs # Heading. The fix is a single space after the hash marks.
2. No blank line before a list
A list that directly follows a paragraph line may not be recognised, depending on the parser. Put a blank line between the paragraph and the list.
3. Expecting a single newline to start a new line
In standard Markdown, one newline inside a paragraph is treated as a space. To get a line break, end the line with two spaces or a backslash, or use a blank line to start a new paragraph. Some chat apps behave differently, which is why text can look fine in one place and collapse in another.
4. Inconsistent list indentation
Nested lists depend on indentation. Mixing two-space, four-space and tab indents can flatten or misnest items. Pick four spaces (the safest across parsers) and stick to it. Setting your editor to insert spaces for the Tab key avoids tab characters creeping in.
5. A table without a separator row
A table needs the row of hyphens under the header. Without it you get literal pipes. Also confirm the header and separator have the same number of columns. See how to write Markdown tables.
6. Unescaped special characters
An asterisk, underscore, backtick, bracket or hash at the wrong place is read as formatting. A line like 2 * 3 * 4 may turn the middle into italics. Escape the characters with a backslash: 2 \* 3 \* 4, or put the expression in backticks.
7. Broken links from spaces and parentheses
A URL with a space or an unbalanced parenthesis ends the link early. Encode spaces as %20, or wrap the URL in angle brackets: [text](<my file.pdf>) in CommonMark. Check link text and target are in the right order: text in square brackets first, URL in parentheses second.
8. Code fences that never close
An opening three-backtick fence with no closing fence turns the rest of the document into one code block. If your page suddenly goes monospaced halfway down, search for the unmatched fence. If your code itself contains three backticks, use a longer fence, such as four backticks, around it.
9. Relying on features your renderer lacks
Tables, task lists and strikethrough come from GitHub Flavored Markdown, not core CommonMark. If they do not render, the tool may not support them. See Markdown flavors explained.
10. Saving in the wrong format
Editors that save as rich text, or add a byte order mark or smart quotes, can break Markdown. Curly quotes in place of straight quotes do not affect prose, but they will break anything inside code. Save as plain text in UTF-8, and read about text file encodings if characters look wrong.
A quick way to catch most of these
Preview your document before sharing it. Markdown mistakes are far easier to see rendered than in the source. Docento's Text & Markdown Editor shows a rendered preview alongside the formatting toolbar, and the Find box helps you search for stray markers such as ``` or |.
Takeaway
Most Markdown failures come from missing spaces, missing blank lines, inconsistent indentation and unescaped characters. Learn those four checks, preview in the tool your readers will use, and the rest rarely bites.
