| name | markdown-linter-fixer |
| description | Fix markdownlint errors in markdown files using markdownlint-cli2. Use when asked to "markdown linter fixer", "run markdownlint", "fix markdown lint errors", "fix MD029", or "resolve ordered list issues" across one or more .md files. |
| allowed-tools | Bash, Read, Write, Edit, Glob, Grep |
Markdown Linter Fixer
Contents
Overview
Systematically fix linting issues in *.md files using markdownlint-cli2 through a structured workflow that diagnoses, fixes automatically where possible, and guides manual fixes when needed.
When to Use This Skill
Use this skill when:
- Fixing markdown linting errors in projects
- Standardizing markdown formatting across multiple files
- Addressing ordered list numbering issues (MD029)
- Preparing markdown documentation for quality standards
- Setting up markdown linting for the first time in a project
Workflow Process
Phase 1: Environment Setup & Prerequisites
Verify markdownlint-cli2 Installation
Check if markdownlint-cli2 is installed:
markdownlint-cli2 --version
If missing, install it globally via npm:
npm install -g markdownlint-cli2
Handle any permission or installation errors by suggesting:
- Local installation:
npm install --save-dev markdownlint-cli2
- Using npx:
npx markdownlint-cli2
- User-specific npm directory configuration
Configuration File Check
Look for existing markdown configuration files in the project root:
.markdownlint-cli2.jsonc.markdownlint.json.markdownlint.yaml.markdownlint.yml.markdownlintrc
If none exist, create .markdownlint-cli2.jsonc with:
{
"config": {
"MD013": false
},
"ignores": []
}
This disables max line length warnings while keeping other rules active. The ignores array can be used to exclude specific files from linting (e.g., example files with intentional errors).
IMPORTANT - Configuration Policy:
- Do not ignore/hide linting errors by modifying
.markdownlint-cli2.jsonc
- Only modify the
ignores array based on:
- Explicit user input or approval
- Content from
.gitignore file (files already ignored by git)
- Always ask the user before adding files to the ignore list
- Never suppress errors without user consent - fix them instead
Phase 2: Diagnostic Assessment
Initial Root-Level Scan
Run linter on root-level markdown files:
markdownlint-cli2 "*.md"
Document all issues found, including:
- Error codes (e.g., MD029, MD001, MD032)
- File names and line numbers
- Brief description of each issue
Comprehensive Recursive Scan
Scan all markdown files including subdirectories:
markdownlint-cli2 "**/*.md"
This includes files in directories like:
docs/guides/- Any other subdirectories containing markdown
Create a complete inventory of all issues across the project.
Phase 3: Issue Analysis
Categorize Errors by Type
Group all identified linting errors by error code:
- Track frequency of each error type
- Identify which errors are auto-fixable
- Flag special attention areas (especially MD029, which often requires understanding indentation issues)
Common error types:
- MD001: Heading levels should increment by one level at a time
- MD009: Trailing spaces
- MD010: Hard tabs
- MD012: Multiple consecutive blank lines
- MD029: Ordered list item prefix (requires special attention - often caused by improper indentation)
- MD032: Lists should be surrounded by blank lines
- MD047: Files should end with a single newline character
Document patterns such as:
- "Found 15 MD029 errors across 5 files"
- "MD032 appears in all documentation files"
- "MD029 errors primarily in files with code blocks within lists"
Phase 4: Automatic Fixes
Execute Auto-Fix
Run the auto-fix command to correct all auto-fixable issues:
markdownlint-cli2 "**/*.md" --fix
This command will:
- Automatically fix formatting issues where possible
- Preserve original content intent
- Modify files in place
Monitor for Issues
Watch for:
- Errors during the fix process
- Files that couldn't be modified (permissions)
- Any unexpected side effects
Document what was fixed automatically versus what remains.
Phase 5: Manual Fixes
Handle MD029 Issues
For remaining MD029 (ordered list item prefix) issues:
Load and consult references/MD029-Fix-Guide.md for detailed guidance on:
- Understanding the root cause: improper indentation of content between list items
- Proper 4-space indentation for code blocks within lists
- Indentation requirements for paragraphs, blockquotes, and nested content
- Common mistakes and how to avoid them
- Real-world examples showing before/after fixes
- Alternative solutions and when to use them
Key insight: MD029 errors often occur when code blocks, paragraphs, or other content between list items lack proper indentation (typically 4 spaces), causing markdown parsers to break list continuity.
Apply Manual Corrections
For issues not auto-fixed:
- Open affected files
- Apply fixes according to error type
- Maintain consistency with existing markdown style
- Verify fixes don't break content
Phase 6: Verification & Reporting
Re-run Linter
Confirm all issues are resolved:
markdownlint-cli2 "**/*.md"
If no errors appear, linting is complete. If errors remain, document them for additional manual fixes.
Generate Summary Report
Provide a comprehensive summary including:
-
Files Processed
- Total count
- List of files modified
- Any files skipped or with errors
-
Issues Fixed by Type
- Count of each error type fixed
- Auto-fixed vs. manually fixed
- Special notes on MD029 fixes
-
Remaining Issues (if any)
- Error codes still present
- Files requiring manual attention
- Recommended next steps
-
Completion Status
- Confirmation of successful completion, or
- Clear explanation of remaining work needed
- Any error details with suggested solutions
Quick Reference Checklist
Key Principles
- Preserve content intent: fix formatting without changing meaning.
- Respect project configuration: do not override existing lint rules unless explicitly requested.
- Do not suppress or hide errors without user consent; fix issues rather than masking them.
- Apply progressive fixing: auto-fix first, then manual fixes for remaining issues.
- Report clearly: what was found, what was fixed, and what still needs action.
Common Scenarios
| User Request Pattern | Workflow Emphasis | References |
|---|
| "Set up markdown linting for my documentation" | Phase 1 -> Phase 2 -> Phase 4 -> Phase 6 | N/A |
| "Fix all markdown linting errors in my project" | Phase 2 -> Phase 3 -> Phase 4 -> Phase 5 -> Phase 6 | Load MD029/MD036 guides only if related errors remain |
| "Fix MD029" / "ordered list issues" | Phase 2 (target MD029) -> Phase 4 -> Phase 5 -> Phase 6 | references/MD029-Fix-Guide.md |
Resources
references/
MD029-Fix-Guide.md
Comprehensive guide for handling MD029 (ordered list item prefix) errors, focusing on the root cause: improper indentation. This reference provides:
- Explanation of why MD029 errors occur (content breaking list continuity)
- Proper indentation rules: 4 spaces for code blocks, paragraphs, and other content
- Indentation table showing requirements for different content types
- Common mistakes with clear ❌ wrong vs ✅ correct examples
- Real-world before/after examples
- Alternative solutions and when to use markdownlint-disable comments
- Best practices for maintaining list continuity
- Verification steps
Load this file when MD029 errors persist after auto-fix, or when user needs guidance on fixing ordered list issues. The guide is particularly valuable when lists contain code blocks or mixed content.
MD036-Guide.md
Comprehensive style guide for avoiding MD036 (no emphasis as heading) errors. This reference provides:
- Clear explanation of the MD036 rule and why it matters
- Wrong vs. correct examples showing bold text vs. proper heading syntax
- Heading level hierarchy guidelines (h1 through h6)
- Common violations to avoid when creating markdown files
- Best practices for using headings vs. bold text
- Quick checklist for markdown file creation and modification
Load this file when creating new markdown documentation or when encountering MD036 errors. Use as a reference to maintain consistent heading structure and avoid using bold text as heading substitutes.
