---

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-linters for complete linting
• Configuration: .markdownlint.yaml
• Markdown standards: CLAUDE.md