s2005/markdown-linter-fixer-skill

Overview

This skill systematically fixes linting issues in Markdown files using markdownlint-cli2. It automates diagnosic scans, applies safe auto-fixes, and guides manual corrections—with special attention to ordered list numbering (MD029). The workflow preserves content intent and produces a clear verification report.

How this skill works

The skill verifies or installs markdownlint-cli2, locates project configuration, and runs root-level and recursive scans to inventory lint errors by code, file, and line. It executes markdownlint-cli2 --fix for auto-fixable issues, then identifies remaining problems (especially MD029) and provides targeted guidance for manual fixes. Finally, it re-runs the linter and generates a summary report of actions and outstanding items.

When to use it

• When you need to fix linting errors across a repository of .md files
• When standardizing markdown formatting across docs and guides
• When ordered list numbering (MD029) errors appear or persist
• When preparing documentation for release or CI checks
• When setting up markdownlint-cli2 in a new project

Best practices

• Verify markdownlint-cli2 availability; prefer npx or local dev install if global npm permissions are restricted
• Respect existing .markdownlint* configuration; only modify ignores with explicit user consent
• Run auto-fixes first, then handle remaining issues manually to avoid altering intent
• Preserve content meaning—avoid changing wording unless necessary for formatting
• Re-run the linter and produce a concise report documenting fixes and remaining work

Example use cases

• Install linting and fix all auto-fixable issues before a docs release
• Scan a docs/ directory to find and correct MD032 and MD029 problems
• Resolve MD029 errors in lists that include code blocks by applying proper indentation
• Create a verification report for CI that lists files modified and error counts
• Set up a project-level .markdownlint-cli2.jsonc with agreed rules and run a baseline scan