Common Markdown Mistakes (And How to Fix Them)

Most Markdown errors come from small syntax mistakes rather than complicated problems. A missing space, an extra character, or an incorrect file path is often enough to change how a document is rendered.

Different Markdown editors and platforms may also support slightly different features, so a document that works in one editor might not look exactly the same somewhere else.

This guide is useful for anyone who writes Markdown regularly, including:

• Beginners learning Markdown
• Developers writing GitHub README files
• Technical writers
• Students taking notes
• Bloggers and content creators
• Documentation teams

If you've ever wondered why your headings, tables, images, or code blocks don't display correctly, this guide will help you find and fix the problem.

This guide covers mistakes related to:

Before fixing individual mistakes, remember a few simple rules:

• Use only one H1 heading in a document.
• Keep heading levels in order.
• Leave blank lines where needed.
• Close every code block.
• Preview your document before publishing.

Following these basics prevents many common formatting problems.

Headings organize your document and make it easier to read. They also help search engines, documentation tools, and screen readers understand the structure of your content.

See Markdown Headings for complete hierarchy rules.

Mistake #1: Forgetting the space after #

❌ Incorrect

#Heading

✅ Correct

# Heading

Without the space, many Markdown parsers treat the line as plain text instead of a heading.

Mistake #2: Using multiple H1 headings

❌ Incorrect

# Project
...
# Installation

✅ Correct

# Project

## Installation

## Usage

Use one H1 for the page title, then organize the rest of the content with H2 and H3 headings.

Mistake #3: Skipping heading levels

❌ Incorrect

# Title

### Features

✅ Correct

# Title

## Features

### Installation

Keep headings in order so the document has a clear structure.

Mistake #4: Using headings only to make text bigger

Instead of creating a heading just to emphasize text, use bold text or a blockquote when appropriate.

✅ Better

**Important:** Save your changes before publishing.

Mistake #5: Mixing heading styles

Choose one capitalization style and use it consistently throughout the document.

✅ Good examples

## Installation Guide

## Configuration

## Troubleshooting

Consistent headings make documentation easier to read and navigate.

Lists make content easier to scan, but small formatting mistakes can break the layout or create inconsistent formatting.

See Markdown Lists for ordered, unordered, and nested list syntax.

Mistake #6: Mixing bullet styles

❌ Incorrect

- First item
* Second item
+ Third item

✅ Correct

- First item
- Second item
- Third item

Markdown supports -, *, and +, but it's best to use the same bullet style throughout a document for consistency.

Mistake #7: Incorrect nested list indentation

❌ Incorrect

- Frontend
- React
- Vue

✅ Correct

- Frontend
  - React
  - Vue

Indent nested items with spaces so they appear under the correct parent item.

Mistake #8: Breaking numbered lists

❌ Incorrect

1. Install
4. Configure
8. Run

✅ Correct

1. Install
2. Configure
3. Run

Keeping numbered lists in order makes instructions easier to follow.

💡 Tip: Some Markdown editors automatically renumber lists, but writing them correctly improves readability in the source file.

Mistake #9: Forgetting the space after list markers

❌ Incorrect

-Item one
*Item two

✅ Correct

- Item one
* Item two

Like headings, list markers should be followed by a space. Without it, some Markdown parsers may not recognize the list correctly.

Broken links and missing images are common problems in Markdown documents. Checking them before publishing improves both usability and documentation quality.

See Markdown Links and Markdown Images for reference syntax and alt text guidance.

Mistake #10: Using incorrect link syntax

❌ Incorrect

[Markdown Guide](https://example.com

✅ Correct

[Markdown Guide](https://example.com)

Always make sure every opening bracket and parenthesis has a matching closing character.

Mistake #11: Using vague link text

❌ Poor

Click here

✅ Better

Read the Markdown Syntax Guide

Descriptive link text tells readers where the link goes and also improves accessibility.

Mistake #12: Using the wrong image path

❌ Incorrect

![Logo](logo.png)

✅ Correct

![Logo](images/logo.png)

If an image doesn't appear, check that the file path is correct and the file actually exists in that location.

Mistake #13: Missing alt text

❌ Poor

![](diagram.png)

✅ Better

![Project architecture diagram](diagram.png)

Alt text helps screen readers understand images and provides context if an image fails to load.

Mistake #14: Using spaces in image filenames

❌ Less reliable

Project Logo.png

✅ Better

project-logo.png

Using lowercase letters with hyphens makes filenames easier to manage across different operating systems and web servers.

Markdown tables are simple to write, but even a small formatting mistake can stop them from rendering correctly.

See Markdown Tables for alignment and GitHub GFM syntax.

Mistake #15: Missing the separator row

❌ Incorrect

| Name | Role |
| John | Developer |

✅ Correct

| Name | Role |
| --- | --- |
| John | Developer |

Every Markdown table needs a separator row between the header and the data.

Mistake #16: Uneven columns

❌ Incorrect

| Name | Role |
| --- | --- |
| John |

✅ Correct

| Name | Role |
| --- | --- |
| John | Developer |

Each row should contain the same number of columns as the header.

Use the Markdown Table Formatter to clean up messy tables.

Mistake #17: Forgetting to escape pipe characters

If your table content contains the | character, Markdown may treat it as a column separator.

❌ Incorrect

| Syntax |
| a | b |

✅ Correct

| Syntax |
| --- |
| a \| b |

Escape the pipe with a backslash (\) so it displays correctly inside the cell.

Using tables for page layout

Tables should organize data, not control page layout.

Good uses include:

• Feature comparisons
• Pricing
• API response codes
• Specifications
• Compatibility charts

Avoid using tables just to align text on the page.

Code blocks are one of the most common parts of Markdown documentation. Using the correct syntax keeps code readable and enables syntax highlighting.

See Markdown Code Blocks for fenced blocks and language identifiers.

Mistake #18: Forgetting to close a code block

Every fenced code block needs a matching closing set of three backticks. If you forget it, everything that follows gets treated as part of the same code block until the next closing fence is found.

✅ Correct

console.log("Hello");

Always add the closing backticks as soon as you open a code block, before writing the code inside it.

Mistake #19: Not specifying the language

❌ Basic

```
const name = "Markdown";
```

✅ Better

```javascript
const name = "Markdown";
```

Adding the language enables syntax highlighting in most Markdown editors and platforms. Common language identifiers include javascript, typescript, python, html, css, json, bash, and sql.

Mistake #20: Using inline code for multiple lines

❌ Incorrect

`const a = 1;
const b = 2;`

✅ Correct

```javascript
const a = 1;
const b = 2;
```

Use inline code for short commands or variable names, and fenced code blocks for multiple lines of code.

Using too many code blocks

Not every command or filename needs its own block. Instead of writing several tiny code blocks, combine related commands into one.

Example:

git clone https://github.com/example/project
cd project
npm install
npm start

This is easier to read and takes up less space.

These issues don't always break your document, but they can make it harder to read and maintain.

Mistake #21: Missing blank lines

Markdown uses blank lines to separate sections.

❌ Incorrect

# Heading
Paragraph
- List item

✅ Better

# Heading

Paragraph

- List item

Adding blank lines makes documents easier to read and helps Markdown parsers understand the structure.

Mistake #22: Inconsistent emphasis

❌ Inconsistent

**Important**
__Note__
*Example*

✅ Better

Choose one style and use it consistently throughout the document.

Mistake #23: Long paragraphs

Large blocks of text are difficult to scan.

Instead of writing one long paragraph, split related ideas into shorter paragraphs or use lists where appropriate.

Mistake #24: Forgetting to preview your document

Markdown can render differently depending on the editor or platform.

Before publishing, preview your document to check:

• Headings
• Lists
• Tables
• Images
• Links
• Code blocks

A quick preview helps catch formatting issues before someone else sees them.

Use the Markdown Editor to preview before you publish.

Many Markdown editors support additional features, but not every platform supports the same extensions.

Assuming HTML works everywhere

Most Markdown processors allow basic HTML, but some platforms remove certain tags for security reasons.

Before using HTML, check whether your editor or platform supports it.

See Markdown HTML and Markdown vs HTML for supported tags and when to use each format.

Using unsupported extensions

Features like Mermaid diagrams, task lists, footnotes, or LaTeX depend on the Markdown implementation.

For example:

• GitHub supports task lists.
• Some editors support Mermaid diagrams.
• Some static site generators support footnotes.
• Basic Markdown parsers may support none of these.

Always verify compatibility before relying on advanced syntax.

Mixing Markdown styles

Try to keep formatting consistent throughout a document.

For example:

• Use one bullet style.
• Use one heading style.
• Keep code block formatting consistent.
• Follow the same table format everywhere.

Consistency makes documents easier to read and maintain.

💡 Pro tip: If something doesn't render as expected, test it in a live Markdown editor before assuming the syntax is wrong. Many formatting issues are caused by using a parser that doesn't support a particular Markdown feature.

Before you publish a Markdown document, take a minute to review it. A quick check can prevent formatting issues and make your content easier to read.

Use this checklist:

• Only one H1 on the page
• Headings follow a logical order (H2 → H3 → H4)
• Lists use consistent indentation
• Links open the correct destination
• Images include descriptive alt text
• Tables have the correct number of columns
• Every code block is closed properly
• Code blocks include a language where possible
• Remove empty sections before publishing
• Preview the document before sharing it

If you're working on important documentation, preview the file in your preferred Markdown editor before publishing. A quick review usually catches small formatting mistakes that are easy to miss while writing.

Most Markdown mistakes are small, but they can affect how your document looks and how easy it is to read.

Using consistent headings, lists, tables, links, images, and code blocks will help you create documentation that works across GitHub, documentation sites, note-taking apps, and most Markdown editors.

As you write more Markdown, these best practices become second nature, making it easier to create clean and professional documents every time.