Home/Docs/Common Markdown Mistakes

Common Markdown Mistakes

Learning Markdown is simple, but even experienced users occasionally make formatting mistakes. A missing space, an incorrect file path, or an unclosed code block can cause your document to render differently than expected.

Fortunately, most Markdown problems are easy to identify and fix once you understand the rules.

This guide explains the most common Markdown mistakes, shows why they happen, and provides the correct way to write Markdown. Whether you're creating GitHub README files, technical documentation, blog posts, or personal notes, avoiding these mistakes will help you write cleaner and more reliable Markdown.

🟢 Practice as you read: Open the Markdown Editor to test fixes with live preview, or run the Markdown Link Checker to catch broken links before publishing.

Open EditorDownload PDF

Why Do Markdown Mistakes Happen?

Markdown is designed to be easy to read and write, but it still follows a specific syntax.

Many formatting problems happen because of:

  • Missing spaces
  • Incorrect punctuation
  • Broken links
  • Wrong file paths
  • Unsupported Markdown features
  • Mixing different Markdown flavors
  • Small typing mistakes

Even a single missing character can change how Markdown is rendered.

The good news is that once you recognize these common mistakes, you'll be able to fix them in just a few seconds.

Who Should Read This Guide?

This guide is useful for:

  • Beginners learning Markdown
  • Developers writing GitHub README files
  • Technical writers
  • Students creating notes
  • Bloggers using Markdown editors
  • Documentation teams
  • Anyone troubleshooting Markdown formatting

If you've ever wondered why your headings, tables, images, or code blocks don't work correctly, this guide is for you.

What You'll Learn

In this guide, you'll learn how to avoid mistakes related to:

  • Headings
  • Paragraphs
  • Lists
  • Links
  • Images
  • Tables
  • Code blocks
  • Task lists
  • Footnotes
  • HTML
  • GitHub Flavored Markdown
  • Mermaid diagrams
  • Mathematical equations

You'll also learn general writing habits that make Markdown documents easier to read and maintain.

How This Guide Is Organized

Each mistake follows the same format so it's easy to understand.

For every example you'll see:

  • The incorrect syntax
  • The correct syntax
  • Why the mistake happens
  • How to avoid it in the future

This practical approach helps you fix problems quickly while also learning the correct Markdown syntax.

Before You Start

Don't worry if you've made some of these mistakes before.

Almost every Markdown user runs into formatting problems while learning.

The goal isn't to memorize every rule. Instead, focus on understanding the common patterns.

Once you know what to look for, you'll naturally avoid most Markdown errors.

Mistakes Covered in This Guide

This guide includes more than 35 common Markdown mistakes, grouped into the following categories.

Category Examples
Headings Missing spaces, incorrect heading levels
Lists Mixed list markers, bad indentation
Links Broken URLs, incorrect syntax
Images Missing alt text, invalid paths
Tables Uneven columns, missing separators
Code Blocks Unclosed fences, missing language names
GitHub Unsupported features, formatting differences
General Inconsistent formatting, unnecessary HTML

Working through these examples will help you build cleaner Markdown documents with fewer formatting issues.

Heading Mistakes

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

The mistakes below are some of the most common heading errors in Markdown.

See Markdown Headings for complete hierarchy rules.

Mistake #1: Forgetting the Space After `#`

One of the most common beginner mistakes is writing a heading without a space after the hash (#).

❌ Incorrect

#Heading One

✅ Correct

# Heading One

Why This Happens

Many Markdown processors expect a space between the # character and the heading text. Without it, some editors may display the line as plain text instead of a heading.

Best Practice

Always add a single space after every heading marker.

Mistake #2: Using Multiple H1 Headings

Every Markdown document should normally have one main title.

❌ Incorrect

# Project Guide

Some content...

# Installation

✅ Correct

# Project Guide

## Installation

Why This Happens

Users often create another H1 heading because they want larger text.

Instead, use H2 (##) and H3 (###) headings to organize sections.

Best Practice

Use one H1 heading for the document title and organize the rest of the content with lower-level headings.

Mistake #3: Skipping Heading Levels

Headings should follow a logical hierarchy.

❌ Incorrect

# User Guide

### Installation

✅ Correct

# User Guide

## Installation

### Windows

Why This Happens

Skipping heading levels makes long documents harder to follow.

Some documentation generators and accessibility tools also rely on a proper heading hierarchy.

Best Practice

Move through heading levels one step at a time whenever possible.

Mistake #4: Using Headings Only for Styling

Headings should organize information, not simply make text appear larger.

❌ Incorrect

### Important Notice

when the text isn't actually a new section.

✅ Better

Use bold text, a blockquote, or a callout if you only want to emphasize a sentence.

Why This Happens

Many beginners treat headings like font-size controls.

Markdown headings define document structure, not visual appearance.

Best Practice

Create a heading only when introducing a new topic or section.

Mistake #5: Inconsistent Heading Style

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

For example:

✅ Consistent

## Installation Guide
## Configuration Options
## Troubleshooting Tips

Instead of mixing styles like:

## Installation guide
## CONFIGURATION OPTIONS
## troubleshooting Tips

Why This Matters

Consistent headings make documentation look more professional and improve readability.

Readers can scan the page more easily when headings follow the same style.

Quick Checklist for Headings

Before publishing your document, check that:

  • Every heading has a space after the #.
  • The page contains only one H1 heading.
  • Heading levels follow a logical order.
  • Headings describe the content below them.
  • Capitalization is consistent throughout the document.

Following these simple rules will help keep your Markdown documents clean, organized, and easy to navigate.

List Mistakes

Lists are one of the most frequently used Markdown features. They're simple to create, but small formatting mistakes can break the structure or make your document difficult to read.

Here are some common list-related mistakes and how to avoid them.

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

Mistake #6: Mixing Bullet Styles

Markdown supports multiple bullet markers, including hyphens (-), asterisks (*), and plus signs (+).

❌ Incorrect

- Apple
* Banana
+ Orange

✅ Correct

- Apple
- Banana
- Orange

Why It's a Problem

Although many Markdown editors render mixed bullet styles correctly, using different markers in the same list creates an inconsistent appearance and makes documents harder to maintain.

How to Avoid It

Choose one bullet style for your project and use it consistently throughout the document.

Mistake #7: Incorrect Nested List Indentation

Nested lists must be indented correctly.

❌ Incorrect

- Fruits
- Apple
- Orange

✅ Correct

- Fruits
  - Apple
  - Orange

Why It's a Problem

Without indentation, Markdown treats every item as part of the same list instead of creating a parent and child relationship.

How to Avoid It

Use consistent indentation for every nested level. Most editors automatically preserve indentation when you press Tab or indent with spaces.

Mistake #8: Restarting Numbered Lists Unnecessarily

Some users manually restart numbering in the middle of a list.

❌ Incorrect

1. Install
2. Configure

1. Run
2. Test

✅ Better

1. Install
2. Configure
3. Run
4. Test

Why It's a Problem

Restarting numbering without starting a new section can confuse readers and interrupt the flow of instructions.

How to Avoid It

Keep numbered lists continuous unless you're intentionally beginning a completely new sequence.

Mistake #9: Mixing Ordered and Unordered Lists Without Structure

Combining different list types without a clear hierarchy makes documents harder to follow.

❌ Incorrect

1. Install
- Configure
2. Finish

✅ Correct

1. Install
2. Configure

- Optional setting
- Advanced option

3. Finish

Why It's a Problem

Readers expect a logical flow. Randomly switching between numbered and bullet lists can make instructions unclear.

How to Avoid It

Use numbered lists for steps that must be followed in order and bullet lists for related information that doesn't require a sequence.

Mistake #10: Forgetting a Space After the List Marker

A missing space can prevent Markdown from recognizing a list item.

❌ Incorrect

-First Item

✅ Correct

- First Item

Why It's a Problem

Most Markdown processors require a space between the list marker and the text.

Without the space, the content may be displayed as plain text instead of a formatted list.

How to Avoid It

Always insert one space after every bullet or number before writing the list item.

Quick Checklist for Lists

Before publishing your document, check that:

  • Every bullet uses the same marker.
  • Nested items are properly indented.
  • Numbered lists follow a logical order.
  • Every list marker is followed by a space.
  • Ordered and unordered lists are used for the correct purpose.

Consistent list formatting improves readability and makes documentation easier to scan, especially in longer guides.

Mistake #12: Using Generic Link Text

Avoid using vague phrases like "Click Here" or "Read More" as link text.

❌ Poor Example

Click [here](https://example.com)

✅ Better Example

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

Why It's a Problem

Generic link text doesn't tell readers where the link leads. It also reduces accessibility because screen readers often announce only the link text.

How to Avoid It

Use descriptive link text that clearly explains the destination or purpose of the link.

Mistake #13: Using Incorrect Image Paths

Broken image paths are one of the most common Markdown problems.

❌ Incorrect

![Logo](images/logo.png)

when the file doesn't exist in that location.

✅ Correct

![Project Logo](assets/images/logo.png)

Why It's a Problem

If the path is incorrect, the image won't load and readers may only see the alternative text.

How to Avoid It

Double-check file names, folder locations, and capitalization before publishing your document.

Mistake #14: Forgetting Alternative Text

Every image should include meaningful alternative (alt) text.

❌ Poor Example

![](dashboard.png)

✅ Better Example

![Project dashboard showing monthly analytics](dashboard.png)

Why It's a Problem

Alternative text improves accessibility and provides context if the image cannot be displayed.

How to Avoid It

Write a short description that explains what the image shows or why it's included.

Read Markdown Images for alt text best practices.

Mistake #15: Using Spaces in Image File Names

Although some systems handle spaces correctly, they can cause issues on certain platforms or when sharing files.

❌ Less Reliable

![Chart](Sales Report 2025.png)

✅ Better

![Sales Report](sales-report-2025.png)

Why It's a Problem

Spaces may require URL encoding and can increase the chance of broken links or inconsistent behavior across different systems.

How to Avoid It

Use lowercase letters and separate words with hyphens instead of spaces.

Mistake #16: Uneven Columns

Each row in a Markdown table should contain the same number of columns.

❌ Incorrect

| Name | Role |
|------|------|
| Alex |
| Sam | Designer |

✅ Correct

| Name | Role |
|------|------|
| Alex | Developer |
| Sam | Designer |

Why It's a Problem

Uneven columns can cause tables to render incorrectly or make the content difficult to understand.

How to Avoid It

Before publishing, check that every row has the same number of cells.

Use the Markdown Table Formatter to clean uneven tables.

Mistake #17: Forgetting the Separator Row

Markdown tables require a separator line between the header and the data.

❌ Incorrect

| Name | Role |
| Alex | Developer |

✅ Correct

| Name | Role |
|------|------|
| Alex | Developer |

Why It's a Problem

Without the separator row, many Markdown processors won't recognize the content as a table.

How to Avoid It

Always include the separator line immediately below the table headers.

See Markdown Tables for alignment and GFM syntax.

Mistake #18: Using Tables for Page Layout

Markdown tables should display structured data—not control page layout.

Why It's a Problem

Using tables for formatting makes documents harder to maintain and reduces readability.

Tables should compare information, not position content on the page.

How to Avoid It

Use tables only when your content naturally belongs in rows and columns.

For general document structure, rely on headings, paragraphs, and lists instead.

Code Block Mistakes

Code blocks are essential for sharing commands, scripts, and programming examples. A small syntax mistake can completely change how your code is displayed.

Mistake #19: Forgetting to Close a Code Block

Every fenced code block should begin and end with three backticks.

❌ Incorrect

```python
print("Hello, World!")

✅ Correct

```python
print("Hello, World!")


### Why It's a Problem

If the closing backticks are missing, Markdown may treat everything that follows as part of the same code block.

### How to Avoid It

Whenever you open a fenced code block, immediately add the closing backticks before writing your code.

Mistake #20: Not Specifying the Programming Language

While optional, adding the language name greatly improves readability.

❌ Basic

console.log("Hello");

✅ Better

```javascript
console.log("Hello");


### Why It's a Problem

Without a language identifier, many editors cannot apply syntax highlighting, making code harder to read.

### How to Avoid It

Whenever possible, specify the language after the opening backticks.

Mistake #21: Using Inline Code for Large Code Samples

Inline code is intended for short snippets, not entire programs.

❌ Incorrect

`function greet() {
  console.log("Hello");
}`

✅ Correct

Use a fenced code block for multi-line examples.

Why It's a Problem

Large code samples become difficult to read when displayed inline.

How to Avoid It

Reserve inline code for commands, filenames, variables, or short function names. Use fenced blocks for anything longer.

Mistake #22: Incorrect Task List Syntax

Task lists require both square brackets and a space.

❌ Incorrect

-[ ] Write documentation

✅ Correct

- [ ] Write documentation
- [x] Review content

Why It's a Problem

Missing spaces or brackets prevent the task list from rendering correctly.

How to Avoid It

Always use the format - [ ] for incomplete tasks and - [x] for completed tasks.

See Markdown Task Lists for GitHub GFM checkbox syntax.

Mistake #23: Assuming Every Markdown Editor Supports Task Lists

Not all Markdown implementations include GitHub Flavored Markdown features.

Why It's a Problem

Some editors display task list syntax as plain text instead of interactive checkboxes.

How to Avoid It

Check whether your editor supports GitHub Flavored Markdown (GFM) before relying on task lists.

Mistake #24: Forgetting the Space After `>`

A blockquote marker should be followed by a space.

❌ Incorrect

>Important information

✅ Correct

> Important information

Why It's a Problem

Some Markdown processors may not recognize the blockquote correctly without the space.

How to Avoid It

Treat the > symbol the same way as headings and list markers by adding a space before the text.

Mistake #25: Using HTML When Markdown Is Simpler

Markdown already supports most common formatting.

❌ Unnecessary HTML

<strong>Important</strong>

✅ Better Markdown

**Important**

Why It's a Problem

Mixing unnecessary HTML with Markdown reduces readability and makes documents less portable.

How to Avoid It

Use Markdown syntax whenever it provides the same result. Save HTML for cases where Markdown doesn't support the formatting you need.

Read Markdown vs HTML for when to use each format.

Mistake #26: Assuming Every HTML Tag Is Supported

Different platforms allow different HTML elements.

For example, GitHub supports many common tags but may remove or ignore others for security reasons.

Why It's a Problem

Your document may render differently across editors and websites.

How to Avoid It

If you're publishing on GitHub, a documentation platform, or a static site generator, review its Markdown and HTML support before using advanced HTML elements.

See Markdown HTML for supported tags.

Quick Checklist for Code Blocks and Advanced Features

Before publishing your document, make sure that:

  • Every fenced code block has both opening and closing backticks.
  • Programming languages are specified whenever possible.
  • Large code examples use fenced code blocks instead of inline code.
  • Task lists use the correct syntax.
  • Blockquotes include a space after the > symbol.
  • HTML is used only when Markdown cannot achieve the same result.
  • Advanced features are supported by your chosen Markdown editor or platform.

Following these practices will help your documents render consistently and remain easy to maintain across different Markdown environments.

Advanced Markdown Mistakes

As you become more experienced with Markdown, you'll likely use features such as Mermaid diagrams, mathematical equations, footnotes, and GitHub Flavored Markdown. These features are powerful, but they also introduce new opportunities for formatting mistakes.

Mistake #27: Mixing Different Markdown Flavors

Not every Markdown editor supports the same features.

For example, GitHub Flavored Markdown includes task lists and tables, while some basic Markdown editors only support the original syntax.

Why It's a Problem

A document that works perfectly in one editor may not render correctly in another.

How to Avoid It

Before using advanced features, check which Markdown flavor your editor or platform supports.

Mistake #28: Assuming Mermaid Diagrams Work Everywhere

Mermaid diagrams have become very popular, but support is not universal.

❌ Assuming every Markdown editor renders Mermaid automatically.

✅ Verify that your editor or documentation platform includes Mermaid support.

Why It's a Problem

If Mermaid isn't supported, readers may only see the diagram source code instead of the rendered diagram.

How to Avoid It

Test your document in the platform where it will be published before sharing it with others.

See Mermaid Diagrams for platform compatibility.

Mistake #29: Using Incorrect Mermaid Syntax

Even when Mermaid is supported, small syntax errors can prevent diagrams from rendering.

❌ Incorrect

graph TD
A Start --> B End

✅ Correct

graph TD
A[Start] --> B[End]

Why It's a Problem

Mermaid follows its own syntax rules, which are different from standard Markdown.

How to Avoid It

Validate your Mermaid diagrams using the editor's preview or a Mermaid-compatible viewer before publishing.

Mistake #30: Forgetting That Math Requires LaTeX Syntax

Markdown itself doesn't define mathematical notation.

Most editors that support equations use LaTeX syntax.

❌ Incorrect

E = mc^2

when you expect it to render as a formatted equation.

✅ Correct

$$
E = mc^2
$$

Why It's a Problem

Without the required delimiters, mathematical expressions are usually displayed as plain text.

How to Avoid It

Learn the equation syntax supported by your editor and always preview mathematical expressions before publishing.

Read Markdown Math for inline and block equation syntax.

Mistake #31: Ignoring File Organization

Markdown files are often part of larger projects.

Poor organization can make documentation difficult to maintain.

Common Problems

  • Random file names
  • Duplicate documents
  • Deep folder structures
  • Inconsistent naming conventions

Best Practice

Use descriptive file names, organize related documents into folders, and follow a consistent naming convention throughout your project.

Mistake #32: Writing Very Long Paragraphs

Markdown encourages readable content.

Large blocks of text can overwhelm readers, especially in technical documentation.

Why It's a Problem

Long paragraphs make information harder to scan and reduce readability.

How to Avoid It

Break long sections into shorter paragraphs and use headings, lists, and tables where appropriate.

See Markdown Paragraphs for spacing and readability tips.

Mistake #33: Ignoring Accessibility

Good Markdown isn't only about formatting—it's also about making content accessible.

Common accessibility mistakes include:

  • Missing alternative text for images
  • Skipping heading levels
  • Using vague link text
  • Overusing emphasis
  • Poor table structure

Best Practice

Write with accessibility in mind so your documents are easier to use for everyone, including people using assistive technologies.

Mistake #34: Never Previewing the Document

Many formatting problems can be spotted immediately with a preview.

Why It's a Problem

Publishing without reviewing the rendered document increases the chance of broken formatting, incorrect links, or missing images.

How to Avoid It

Always preview your Markdown document before publishing or sharing it.

A quick review often catches small mistakes that are easy to fix.

Use the Markdown Editor or Markdown Viewer to preview before you publish.

Mistake #35: Focusing Only on Syntax Instead of Readability

Correct syntax doesn't automatically create good documentation.

A technically correct document can still be difficult to read if it's poorly organized.

Best Practices

  • Use descriptive headings.
  • Keep paragraphs concise.
  • Group related information together.
  • Use examples whenever possible.
  • Write for your audience, not just for the Markdown processor.

Good documentation combines correct formatting with clear communication.

Read Markdown Best Practices for broader documentation guidelines.

Quick Checklist Before Publishing

Before you publish any Markdown document, ask yourself these questions:

  • Does the document have one clear title?
  • Are the heading levels organized logically?
  • Do all links and images work?
  • Are tables formatted correctly?
  • Have all code blocks been closed?
  • Is syntax highlighting enabled where appropriate?
  • Have I previewed the document?
  • Is the content easy to scan?
  • Are file names descriptive?
  • Is the document accessible and easy to understand?

Taking a few minutes to review your work can prevent many common Markdown problems and create a better experience for your readers.

Best Practices to Avoid Markdown Mistakes

Avoiding Markdown mistakes isn't about memorizing every rule. Instead, it's about developing good writing habits and reviewing your work before publishing.

Here are some best practices that will help you create cleaner, more consistent Markdown documents.

  • Use a single H1 heading for the page title.
  • Follow a logical heading hierarchy.
  • Keep paragraphs short and easy to scan.
  • Use descriptive link text instead of generic phrases.
  • Add meaningful alternative text to every image.
  • Verify that all links and image paths work correctly.
  • Use fenced code blocks for multi-line code examples.
  • Specify the programming language whenever possible.
  • Keep tables simple and well-structured.
  • Preview your document before publishing.
  • Organize Markdown files using clear folder structures.
  • Choose consistent file names with lowercase letters and hyphens.
  • Avoid unnecessary HTML when Markdown provides the same formatting.
  • Check whether advanced features are supported by your Markdown editor.
  • Write for people first and Markdown second.

Building these habits will reduce formatting issues and make your documentation easier to maintain over time.

Summary

Markdown is intentionally simple, but even small syntax mistakes can affect how your documents are displayed.

By understanding the most common Markdown mistakes, following consistent formatting practices, and previewing your work before publishing, you can create documentation that is easier to read, easier to maintain, and more reliable across different platforms.

Whether you're writing GitHub README files, technical documentation, project notes, or personal knowledge bases, avoiding these common mistakes will help you produce cleaner and more professional Markdown documents.

Remember that great Markdown isn't just about correct syntax—it's also about writing clear, organized, and user-friendly content.

Frequently Asked Questions

  1. 1

    What is the most common Markdown mistake?

    The most common mistake is forgetting the required spaces after Markdown syntax characters such as #, >, or -. Small spacing errors can prevent Markdown from rendering correctly.

  2. 2

    Why is my Markdown not rendering correctly?

    Markdown rendering issues are usually caused by incorrect syntax, unsupported features, broken links, missing code fences, or formatting mistakes. Previewing your document before publishing is one of the easiest ways to identify these problems.

  3. 3

    Why isn't my Markdown table working?

    Tables often fail because the separator row is missing or the rows contain an inconsistent number of columns. Every row should have the same number of cells.

  4. 4

    Why isn't my image showing?

    The most common reasons include incorrect file path, missing image file, typing mistakes in the filename, wrong folder location, and uppercase and lowercase filename mismatches. Always verify that the image exists in the specified location.

  5. 5

    Should I use HTML inside Markdown?

    Only when necessary. Markdown is designed to handle most common formatting tasks. HTML should only be used when Markdown doesn't support the formatting you need.

  6. 6

    Does every Markdown editor support the same features?

    No. Different editors support different Markdown flavors and extensions. Features such as task lists, Mermaid diagrams, footnotes, and mathematical equations may not be available everywhere. Always check the documentation for your chosen editor or platform.