Common Markdown Formatting Mistakes and How to Fix Them

By M. Hassan Ali Published January 25, 2025 2 min read

Most Markdown rendering problems trace back to one of a handful of repeat offenders. Here's the list, roughly in order of how often each one actually shows up.

1. Missing a blank line before a list

Here are the steps:
- First step
- Second step

Some parsers won't recognize the list here because there's no blank line separating the paragraph from it. Fix: always leave one empty line between a paragraph and the list that follows it.

2. No space after the heading hash

#Heading

Without a space after #, some parsers treat this as plain text, not a heading. Fix: # Heading, always with a space.

3. Inconsistent list markers mid-list

- Item one
* Item two

Mixing - and * within the same list can cause some parsers to treat it as two separate lists with a gap between them. Fix: pick one marker and use it for the whole list.

4. Unclosed emphasis markers

This is *italic but never closed

A single unmatched asterisk or underscore can cause everything after it to render as italic until the parser finds a closing match somewhere much later in the document. Fix: always close what you open, and count your asterisks in anything long or complex.

5. A link with a stray space

[link text] (https://example.com)

That space between the closing bracket and the opening parenthesis breaks the link — it needs to be immediately adjacent. Fix: [link text](https://example.com), no space.

6. Forgetting to close a code fence

A triple-backtick block that never gets a matching closing triple-backtick will often swallow the rest of the document into what looks like one giant code block. Fix: always check you have a matching pair of triple-backtick lines.

The fastest way to catch these

Paste your Markdown into the Markdown to HTML tool before publishing anywhere — if something looks wrong in the rendered preview, it's almost always one of the six issues above.

Frequently asked questions

Why did my whole document suddenly turn into a code block?: This is almost always an unclosed triple-backtick fence somewhere earlier in the file — check for a fence that opened but was never closed.