Markdown provides simple syntax for writing structure documents, but most written markdown would not pass a linter check. Here's a list of 11 common syntax mistakes and how to fix them.
See "Linting Markdown files with markdownlint" for instructions on a popular tool to check for these mistakes.
Apr 5, 2023 · 2 min read
Markdown's syntax is easy to learn, and even though the syntax is forgiving, linting can help you avoid unexpected issues.
Empty lines and whitespace
Missing empty lines surrounding blocks
This is probably the most common mistake people make. Blocks of content such as headers, paragraph, lists, and code should have empty lines surrounding them:
# This header should have empty lines surrounding it This paragraph should have empty lines surrounding it - This list - Should have empty lines surrounding it This paragraph should have empty lines surrounding it
# This header has empty lines surrounding it This paragraph has empty lines surrounding it - This list - Has empty lines surrounding it This paragraph has empty lines surrounding it
Missing empty lines between paragraphs
Blocks of content need empty lines surrounding them, but it's especially important with paragraphs. Many markdown renderers won't separate paragraphs unless there's an empty line between them.
This is the first paragraph This is still part of the first paragraph
This is the first paragraph This is the second paragraph
Too many empty lines surrounding blocks
Blocks of content need empty lines surrounding them, but only one, even if having more usually doesn't affect rendering.
# Header Paragraph - List item - List item
# Header Paragraph - List item - List item
No space after header declarations
Without a space after the #'s in your header, markdown renderers may interpret the line as a paragraph rather than a header.
#This is a header? This is a paragraph
# This is a header! This is a paragraph
Leading and trailing whitespace
Markdown uses some whitespace as syntax , so extra whitespace could throw off your formatting. Or at best it's just unnecessary characters.
Paragraph␣ ␣- List ␣- List
Paragraph - List - List
Because markdown uses some whitespace as syntax, mistakes such as inconsistent indentation can throw off rendering.
- An item - A sub item - A sub item - A sub item? 8. Eighth item 9. Ninth item 10. Tenth item 11. Eleventh item
- An item - A sub item - A sub item - A sub item 8. Eighth item 9. Ninth item 10. Tenth item 11. Eleventh item
Ordering and incrementing
Incorrect header incrementing
Heading levels should only increment one level at a time (h1, h2, h3, etc.). There are times when someone might want to ignore this rule for stylistic reasons, but it is technically incorrect.
# Heading 1 ### Heading 2 ##### Heading 3 # Heading 1
# Heading 1 ## Heading 2 ### Heading 3 # Heading 1
Incorrect ordered list prefix incrementing
Markdown renderers are especially forgiving about this rule, but ordered lists should either be written with prefixes that increment one at a time, or prefixes of all 1's.
1. One 4. Two 7. Three 3. One 3. Two 3. Three
1. One 2. Two 3. Three 1. One 1. Two 1. Three
No language for fenced code blocks
Defining a language for fenced code blocks helps renderers apply syntax highlighting, and without a language explicitly defined it'll either be guessed or defaulted as "text".
``` console.log("Hello world!"); ```
Using HTML tags
Most markdown renderers will interpret HTML tags as syntax rather than content, so using unescaped HTML tags could give unexpected results. When using HTML tags for formatting, try to see if there's a native Markdown syntax to achieve the same thing instead.
In HTML, the <p> tag is used for paragraphs. This is the first paragraph<br> <br> This is effectively the second paragraph
In HTML, the `<p>` tag is used for paragraphs. This is the first paragraph This is the second paragraph
Using "bare" URLs
Just like websites wouldn't list out an entire URL without hyperlink text, URLs shouldn't be written out in markdown, especially because renderers may treat them as content and not automatically hyperlink them.
Different markdown specs have different syntax rules, so these rules may not be 100% universal, but should fit for most specs.
Check out some of these different specs: