doc-validate-markdown

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

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the validation of Markdown files using markdownlint to ensure consistent formatting, link integrity, and strict adherence to style guides. It streamlines the documentation process by identifying syntax errors, enforcing structural best practices, and providing auto-fix capabilities for common issues before code is committed.

Use Cases

  • Pre-commit Documentation Audit: Automatically scan markdown files for formatting errors and style violations to ensure high-quality documentation before pushing changes to a repository.
  • CI/CD Pipeline Integration: Incorporate automated markdown linting into continuous integration workflows to prevent merging documentation that fails to meet project standards.
  • Standardizing Project Style: Enforce consistent rules across large-scale documentation sets, such as mandatory code block languages, specific line lengths, and proper heading spacing.
  • Bulk Formatting Correction: Utilize the auto-fix feature to instantly resolve common issues like trailing whitespace, incorrect nesting, or missing blank lines across multiple files.
namedoc-validate-markdown
descriptionValidate markdown files for formatting, links, and style compliance using markdownlint. Use before committing documentation changes.
mcp_fallbacknone
categorydoc

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