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.
npx claudepluginhub s2005/markdown-linter-fixer-skill --plugin markdown-linter-fixerThis skill is limited to using the following tools:
- [Overview](#overview)
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
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.
Use this skill when:
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:
npm install --save-dev markdownlint-cli2npx markdownlint-cli2Look for existing markdown configuration files in the project root:
.markdownlint-cli2.jsonc.markdownlint.json.markdownlint.yaml.markdownlint.yml.markdownlintrcIf 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:
.markdownlint-cli2.jsoncignores array based on:
.gitignore file (files already ignored by git)Run linter on root-level markdown files:
markdownlint-cli2 "*.md"
Document all issues found, including:
Scan all markdown files including subdirectories:
markdownlint-cli2 "**/*.md"
This includes files in directories like:
docs/guides/Create a complete inventory of all issues across the project.
Group all identified linting errors by error code:
Common error types:
Document patterns such as:
Run the auto-fix command to correct all auto-fixable issues:
markdownlint-cli2 "**/*.md" --fix
This command will:
Watch for:
Document what was fixed automatically versus what remains.
For remaining MD029 (ordered list item prefix) issues:
Load and consult references/MD029-Fix-Guide.md for detailed guidance on:
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.
For issues not auto-fixed:
Confirm all issues are resolved:
markdownlint-cli2 "**/*.md"
If no errors appear, linting is complete. If errors remain, document them for additional manual fixes.
Provide a comprehensive summary including:
Files Processed
Issues Fixed by Type
Remaining Issues (if any)
Completion Status
markdownlint-cli2 --version.markdownlint-cli2.jsonc preferred)markdownlint-cli2 "**/*.md"markdownlint-cli2 "**/*.md" --fixreferences/MD029-Fix-Guide.md and references/MD036-Guide.md as neededmarkdownlint-cli2 "**/*.md"| 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 |
Comprehensive guide for handling MD029 (ordered list item prefix) errors, focusing on the root cause: improper indentation. This reference provides:
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.
Comprehensive style guide for avoiding MD036 (no emphasis as heading) errors. This reference provides:
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.