5.8 KiB
Fixing MD029 Markdownlint Errors: Ordered List Item Prefix
Note: This documentation file has markdownlint rules disabled at the top because it intentionally contains examples of problematic markdown code that would otherwise trigger linting errors. This is a common practice in documentation that demonstrates what NOT to do.
Problem Description
The MD029 markdownlint rule triggers the following error:
MD029/ol-prefix: Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/1/1]
This error occurs when markdownlint detects what it perceives as separate ordered lists instead of a continuous numbered list.
Root Cause
The primary cause of MD029 errors is improper indentation of content between ordered list items. When code blocks, paragraphs, or other content appear between list items without proper indentation, Markdown parsers interpret this as breaking the list continuity.
Example of Problematic Code
1. First item
```bash
some code here
- Second item
<!-- markdownlint-enable MD029 MD032 -->
In the above example, the code block breaks the list, causing item 2 to be seen as starting a new list.
## Solution: Proper Indentation
### For Code Blocks
Indent code blocks with **4 spaces** (or more, depending on nesting level) to maintain list continuity:
```markdown
1. First item
```bash
some code here
```
2. Second item <!-- No MD029 error -->
3. Third item
```bash
another code block
```
4. Fourth item
For Paragraphs
Indent continuation paragraphs with at least 1 space (typically 4 spaces for consistency):
1. First item
This is a continuation paragraph that belongs to item 1.
It should be indented to maintain list continuity.
2. Second item
Another continuation paragraph.
3. Third item
For Mixed Content
You can mix different types of content by maintaining proper indentation:
1. First step
```bash
command --option value
```
This command does something important.
2. Second step
```bash
another-command --flag
```
Additional explanation here.
3. Final step
Indentation Rules
| Content Type | Indentation Required |
|---|---|
| Code blocks (fenced) | 4 spaces minimum |
| Code blocks (indented) | 8 spaces minimum |
| Paragraphs | 4 spaces (recommended) |
| Blockquotes | 4 spaces + > |
| Nested lists | 4 spaces per level |
Common Mistakes to Avoid
❌ Wrong: No indentation
1. Item one
```bash
code here
- Item two
### ❌ Wrong: Insufficient indentation
```markdown
1. Item one
```bash
code here <!-- Only 2 spaces, not enough -->
- Item two
<!-- markdownlint-enable MD029 MD032 MD031 -->
### ✅ Correct: Proper indentation
```markdown
1. Item one
```bash
code here <!-- 4 spaces indentation -->
```
2. Item two <!-- No error -->
Alternative Solutions (Not Recommended)
While the following approaches can technically resolve MD029 errors, they are not recommended as they affect readability and functionality:
Using Only "1." for All Items
1. First item
1. Second item <!-- Auto-numbered by renderer -->
1. Third item
Disabling the Rule
<!-- markdownlint-disable MD029 -->
1. First item
2. Second item
3. Third item
Ignoring MD029 Errors in Specific Sections
Sometimes you need to intentionally include examples of problematic markdown (like in this documentation file). In such cases, you can disable the MD029 rule for specific sections:
<!-- markdownlint-disable MD029 MD032 -->
1. Item one
```bash
code here
- Item two
**When to use this approach:**
- In documentation files showing examples of problematic code
- When demonstrating what NOT to do
- In code examples that are meant to illustrate errors
**Note:** This documentation file itself uses `<!-- markdownlint-disable MD029 -->` at the top to prevent errors from the intentional "bad examples" shown throughout the document.
## Best Practices
1. **Always use 4-space indentation** for content within list items
2. **Maintain consistent indentation** throughout the document
3. **Test your markdown** with a preview to ensure proper rendering
4. **Use fenced code blocks** (```) rather than indented code blocks when possible
5. **Keep list items logically grouped** - if content doesn't belong to a list item, consider restructuring
## Real-World Example
Here's a common scenario showing how proper indentation fixes MD029 errors:
### Before (with MD029 errors):
```markdown
1. Clone the repository
```bash
git clone https://github.com/example/project.git
- Install dependencies
npm install
- Run the application
After (MD029 errors fixed)
1. Clone the repository
```bash
git clone https://github.com/example/project.git
```
2. Install dependencies <!-- No error -->
```bash
npm install
```
3. Run the application <!-- No error -->
```bash
npm start
```
## Verification
After applying the fixes, run markdownlint to verify:
```bash
markdownlint your-file.md
You should see no MD029 errors in the output.
Conclusion
The key to fixing MD029 errors is understanding that Markdown requires proper indentation to maintain list continuity. By indenting code blocks and other content with 4 spaces, you ensure that the markdown parser recognizes them as part of the list items rather than separate elements that break the list.