5 Common Markdown Mistakes (And How to Fix Them)

Even experienced writers make these markdown formatting errors. Learn to spot and fix them to create cleaner, more professional documents.

1. Inconsistent Heading Hierarchy

The Problem

Many writers jump heading levels or use headings inconsistently:

markdown
# Main Title
### Subsection (skipped H2!)
## Another Section
#### Deep subsection (inconsistent)

Why It's Bad

• Breaks document structure
• Hurts accessibility and SEO
• Confuses readers and screen readers
• Makes navigation unreliable

The Fix

Use heading levels sequentially:

markdown
# Main Title (H1)
## Section (H2)
### Subsection (H3)
#### Sub-subsection (H4)
## Another Section (H2)
### Related Subsection (H3)

Best Practices

• Use only one H1 per document
• Don't skip heading levels
• Keep hierarchy logical and consistent
• Use headings for structure, not styling

2. Improper List Formatting

The Problem

Inconsistent spacing and indentation in lists:

markdown
- Item 1
-Item 2 (no space after -)
  - Subitem (wrong indentation)
-   Item 3 (extra spaces)

1. Numbered item
2.No space after number
3. Item three
1. Wrong numbering

Why It's Bad

• Breaks list rendering
• Creates parsing errors
• Makes source hard to read
• Inconsistent visual appearance

The Fix

Use consistent spacing and indentation:

markdown
- Item 1
- Item 2
  - Subitem (2 spaces or 1 tab)
  - Another subitem
- Item 3

1. First numbered item
2. Second numbered item
   - Nested unordered item
   - Another nested item
3. Third numbered item

Best Practices

• Always use space after dash, asterisk, or numbers
• Use 2 spaces or 1 tab for indentation
• Be consistent throughout document
• Test nested lists in your preview

3. Incorrect Link and Image Syntax

The Problem

Missing alt text, broken syntax, or poor link practices:

markdown
[Click here](url)  (bad link text)
![](image.jpg)     (no alt text)
[broken link]      (no URL)
![Alt text](broken-image.jpg)  (broken image)

Why It's Bad

• Poor accessibility for screen readers
• Bad SEO and user experience
• Broken links frustrate users
• Missing images break document flow

The Fix

Use descriptive, accessible syntax:

markdown
[Learn about markdown syntax](https://example.com/markdown-guide)
![Screenshot of the markdown editor interface](./images/editor-screenshot.jpg)
[Documentation homepage][docs-link]

[docs-link]: https://docs.example.com

Best Practices

• Use descriptive link text (not "click here")
• Always include alt text for images
• Test all links regularly
• Use reference-style links for cleaner source
• Consider relative vs absolute paths

4. Mixing Syntax Styles

The Problem

Using different markdown flavors inconsistently:

markdown
**Bold text** and __more bold__ (mixing styles)
*Italic* and _also italic_ (inconsistent)
```code``` and ```
code block
``` (different approaches)

Why It's Bad

• Harder to maintain and read source
• Some parsers handle mixed syntax differently
• Creates confusion for team members
• Looks unprofessional in source

The Fix

Choose one style and stick to it:

markdown
**Bold text** and **more bold text**
*Italic text* and *more italic text*

```javascript
// Consistent code block style
const example = "code";

inline code and more inline code

### Best Practices

- Pick one syntax style and document it
- Use linting tools to enforce consistency
- Set up editor preferences for your team
- Review and update style guides regularly

## 5. Poor Code Block Formatting

### The Problem

Missing language specifications or improper formatting:

```markdown

// No language specified function example() { return "no syntax highlighting"; }

    // Using 4-space indentation instead of fenced blocks
    const code = "harder to read";

`code without proper formatting`

Why It's Bad

• No syntax highlighting
• Harder to read and copy
• Poor accessibility
• Inconsistent presentation across platforms

The Fix

Always specify language and use proper formatting:

markdown
```javascript
// Clear language specification
function example() {
  return "properly highlighted";
}

bash
# Shell commands
npm install package-name
cd project-directory

json
{
  "config": "value",
  "number": 42
}

Use inline code syntax for short snippets and commands.

Best Practices

• Always specify language for code blocks
• Use descriptive comments in examples
• Provide complete, runnable examples
• Use inline code for short references
• Test code examples before publishing

Quick Fix Checklist

Before publishing any markdown document:

Structure

• Single H1 at the top
• Sequential heading hierarchy
• Logical document flow

Formatting

• Consistent list indentation
• Proper spacing around elements
• Consistent emphasis styling

Links and Images

• All links work and have descriptive text
• All images have alt text
• Relative paths are correct

Code

• Language specified for all code blocks
• Inline code used appropriately
• Examples are complete and tested

Overall

• Preview looks correct
• Source is clean and readable
• Style is consistent throughout

Tools to Help

Linters

• markdownlint - VS Code extension and CLI tool
• remark-lint - Configurable markdown linter
• textlint - Natural language linting

Editors

• Typora - WYSIWYG markdown editor
• Mark Text - Real-time preview editor
• VS Code - With markdown extensions

Validators

• markdown-link-check - Automated link validation
• Alex - Catches insensitive writing
• Write Good - Prose improvement suggestions

Creating a Style Guide

Document your team's markdown conventions:

markdown
# Markdown Style Guide

## Headings
- Use # for H1, ## for H2, etc.
- Only one H1 per document
- Don't skip heading levels

## Emphasis
- Use **bold** for bold text
- Use *italic* for italic text
- Use code syntax for inline code

## Lists
- Use dash for unordered lists
- Use 2 spaces for indentation
- Add blank line before and after lists

## Links
- Use descriptive link text
- Prefer reference-style for repeated links
- Always include alt text for images

Conclusion

Avoiding these common markdown mistakes will make your documents more professional, accessible, and maintainable. The key is consistency and attention to detail.

Remember:

1. Structure matters - Use headings properly
2. Be consistent - Pick one style and stick to it
3. Test everything - Preview your work and check links
4. Think accessibility - Include alt text and descriptive links
5. Keep it clean - Readable source is maintainable source

Start implementing these fixes gradually, and soon writing clean markdown will become second nature.

Want to practice? Try writing and previewing your markdown in MarkGenie's live editor to catch these mistakes before they make it to production!