doc-validate-markdown

Validate markdown files for formatting, links, and style compliance using markdownlint. Use before committing documentation changes.

⭐8stars🔀4forks📁View on GitHub🕐Updated Jan 3, 2026⬇️2downloads

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.
namedoc-validate-markdown
descriptionValidate markdown files for formatting, links, and style compliance using markdownlint. Use before committing documentation changes.
mcp_fallbacknone
categorydoc
user-invocablefalse

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