doc-validate-markdown
Validate markdown files for formatting, links, and style compliance using markdownlint. Use before committing documentation changes.
When & Why to Use This Skill
The Validate Markdown skill is a specialized tool designed to automate the linting and validation of Markdown documentation. By leveraging markdownlint, it ensures that all .md files adhere to strict formatting, link integrity, and style standards. This skill is essential for maintaining professional, consistent, and error-free documentation across software projects, helping users catch common mistakes like missing code block languages or improper spacing before they reach production.
Use Cases
- Pre-commit Validation: Automatically check documentation changes against style guides and formatting rules before committing to version control to maintain a clean repository.
- CI/CD Error Resolution: Quickly identify and fix specific markdown linting failures reported in automated build pipelines to ensure successful deployments.
- Documentation Standardization: Enforce uniform rules for headings, lists, and code blocks across large-scale knowledge bases to ensure a consistent reader experience.
- Automated Formatting Fixes: Streamline the editing process by using auto-fix capabilities to instantly correct common syntax issues like trailing whitespace or missing newlines.
| name | doc-validate-markdown |
|---|---|
| description | Validate markdown files for formatting, links, and style compliance using markdownlint. Use before committing documentation changes. |
| mcp_fallback | none |
| category | doc |
| user-invocable | false |
Validate Markdown Skill
Validate markdown formatting and style compliance.
When to Use
- Before committing documentation
- Markdown linting errors in CI
- Creating new documentation
- Updating existing docs
Quick Reference
# Check all markdown
npx markdownlint-cli2 "**/*.md"
# Check specific file
npx markdownlint-cli2 README.md
# Fix auto-fixable issues
npx markdownlint-cli2 --fix "**/*.md"
Common Issues & Fixes
MD040: Code blocks need language
❌ Wrong - missing language:
code here
✅ Correct - has language:
code here
MD031: Blank lines around blocks
❌ Wrong - no blank lines between text and code block.
✅ Correct - add one blank line before the opening fence and one after the closing fence.
MD013: Line too long
Keep lines under 120 characters. Break long sentences at natural boundaries (clauses, lists).
Configuration
.markdownlint.yaml:
line-length:
line_length: 120
code_blocks: false
tables: false
Validation Checklist
- All code blocks have language specified (
```python) - All code blocks have blank lines before and after
- All lists have blank lines before and after
- All headings have blank lines before and after
- No lines exceed 120 characters
- File ends with newline
- No trailing whitespace
Error Handling
| Error | Fix |
|---|---|
| MD040: Missing language tag | Add language: ```mojo |
| MD031: Missing blank lines | Add blank line before/after block |
| MD013: Line too long | Break line at 120 characters |
| MD022: Heading spacing | Add blank line before/after heading |
Workflow
# 1. Validate your changes
npx markdownlint-cli2 "**/*.md"
# 2. If issues, fix auto-fixable ones
npx markdownlint-cli2 --fix "**/*.md"
# 3. Manually fix remaining issues
# 4. Verify no errors
npx markdownlint-cli2 "**/*.md"
# 5. Commit
git add .
git commit -m "docs: update documentation"
References
- Related skill:
quality-run-lintersfor complete linting - Configuration:
.markdownlint.yaml - Markdown standards: CLAUDE.md