2.8 KiB
Common Markdown Pitfalls
Detailed examples of common mistakes and how to fix them.
Pitfall #1: Inconsistent Heading Styles
Problem: Mixing ATX and setext heading styles
# Heading 1
Heading 2
---------
Why it fails: MD003 requires consistent heading style (we use ATX)
Better:
# Heading 1
## Heading 2
Pitfall #2: Missing Code Block Languages
Problem: Fenced code blocks without language specifiers
```
code here
```
Why it fails: MD040 requires language specification for syntax highlighting
Better:
```javascript
code here
```
Pitfall #3: Using Indented Code Blocks
Problem: Using indentation instead of fences
Some text
code here
more code
Why it fails: MD046 requires fenced code blocks (our style setting)
Better:
Some text
```javascript
code here
more code
```
Pitfall #4: Trailing Whitespace
Problem: Invisible spaces at end of lines (hard to spot)
Why it fails: MD009 - trailing spaces can cause rendering issues
Better: Configure editor to show/remove trailing whitespace automatically
Pitfall #5: No Blank Lines Around Elements
Problem:
# Heading
Content immediately after
- List item
More content
Why it fails: MD022, MD032 require spacing for readability
Better:
# Heading
Content with proper spacing
- List item
More content
Pitfall #6: Disallowed Inline HTML
Problem: Using HTML elements not in our allowed list
This is <span style="color: red">red text</span>
Why it fails: MD033 - only specific elements are allowed
Better: Use markdown emphasis or allowed HTML elements:
This is **important text**
Use <kbd>Ctrl</kbd>+<kbd>C</kbd> to copy
Pitfall #7: Skipping Heading Levels
Problem:
# Main Heading
### Subheading (skipped H2)
Why it fails: MD001 requires proper heading hierarchy
Better:
# Main Heading
## Section Heading
### Subheading
Pitfall #8: Multiple Top-Level Headings
Problem:
# Introduction
Some content
# Another Top-Level Heading
Why it fails: MD025 requires single H1 per document
Better:
# Introduction
## Another Section Heading
Pitfall #9: Bare URLs
Problem:
Check out https://example.com for more info
Why it fails: MD034 requires proper link syntax
Better:
Check out <https://example.com> or [Example Site](https://example.com) for more info
Pitfall #10: Inconsistent List Markers
Problem:
- Item one
* Item two
- Item three
Why it fails: MD004 requires consistent list markers
Better:
- Item one
- Item two
- Item three