Comprehensive markdown linting guidance using markdownlint-cli2. Run, execute, check, and validate markdown files. Fix linting errors (MD0XX rules). Configure .markdownlint-cli2.jsonc (rules and ignores). Set up VS Code extension and GitHub Actions workflows. Use when working with markdown files, encountering validation errors, configuring markdownlint, setting up linting workflows, troubleshooting linting issues, or establishing markdown quality standards.
Limited to specific tools
Additional assets for this skill
This skill is limited to using the following tools:
references/best-practices.mdreferences/github-actions-config.mdreferences/installation-setup.mdreferences/intelligent-fixing-guide.mdreferences/markdownlint-rules.mdreferences/vscode-extension-setup.mdscripts/README.mdThis skill provides comprehensive guidance for markdown linting using markdownlint-cli2, the industry-standard markdown linter that can be used in any project.
This tooling enables enforcement of strict markdown quality standards through automated linting. Markdown files can be validated using markdownlint-cli2 with a unified tooling approach that ensures zero configuration drift across VS Code, CLI, and CI/CD environments.
Core Philosophy:
.markdownlint-cli2.jsonc contains all configuration (rules, ignores, options)markdownlint-cli2 engine everywhere (VS Code, CLI, CI/CD)This skill should be used when:
.markdownlint-cli2.jsonc (rules, ignores, or options)If this is your first time setting up markdown linting, see the comprehensive installation guide:
This guide covers:
.markdownlint-cli2.jsonc)Quick detection check:
# Check if you're already set up
ls .markdownlint-cli2.jsonc # Configuration exists?
npm list markdownlint-cli2 # Package installed?
cat package.json | grep "lint:md" # Scripts configured?
If any of these are missing, follow the Installation and Setup Guide first.
Option 1: Using npx (zero setup required):
# Check all markdown files
npx markdownlint-cli2 "**/*.md"
# Auto-fix issues
npx markdownlint-cli2 "**/*.md" --fix
Option 2: Using npm scripts (if configured):
# Check all markdown files for linting errors
npm run lint:md
# Auto-fix fixable linting issues
npm run lint:md:fix
Option 3: VS Code extension for real-time linting (optional/advanced):
davidanson.vscode-markdownlint from VS Code marketplace.markdownlint-cli2.jsonc configuration (see installation guide)When configured, markdownlint-cli2 can be used everywhere to ensure zero configuration drift:
CLI Tool (markdownlint-cli2) - Core component, use this first
VS Code Extension (davidanson.vscode-markdownlint) - Optional/Advanced
markdownlint-cli2 engine as CLI.vscode/settings.json)GitHub Actions (markdownlint-cli2-action) - Optional/Advanced
All tools read .markdownlint-cli2.jsonc in the project root as the single source of truth:
{
"gitignore": true,
"ignores": ["vendor/**/*.md"],
"config": {
"default": true,
"MD013": false
}
}
What this contains:
gitignore: Automatically excludes files from .gitignoreignores: Additional glob patterns to exclude from lintingconfig: Linting rules (all defaults enabled, MD013 disabled for long lines)Configuration precedence (in decreasing order):
.markdownlint-cli2.{jsonc,yaml,cjs} file - Single source of truthNote: Changes to .markdownlint-cli2.jsonc apply instantly to all tools (VS Code, CLI, GitHub Actions)
IMPORTANT - Read this before modifying any configuration:
.markdownlint-cli2.jsonc without explicit approvalCorrect approach:
Error: MD022/blanks-around-headings - Headings should be surrounded by blank lines
Action: Add blank lines before and after the heading in the markdown file
Incorrect approach:
Error: MD022/blanks-around-headings - Headings should be surrounded by blank lines
Action: Disable MD022 rule in .markdownlint-cli2.jsonc
Exception: If you genuinely believe a rule should be modified, present your case to the user with:
The user will make the final decision on whether to modify the configuration.
When running linting validation, ALWAYS automatically fix ALL errors (both fixable and "unfixable") without asking for user confirmation.
Workflow:
--fix flag) without promptingDO NOT ask "Would you like me to auto-fix?" or "Would you like me to investigate?" - just fix everything automatically.
For npx approach (zero setup):
For local install approach:
# Install dependencies (first time only)
npm install
If your project doesn't have markdownlint-cli2 installed, see the Installation and Setup Guide.
With npx:
npx markdownlint-cli2 "**/*.md"
With npm scripts (if configured):
npm run lint:md
What this does:
markdownlint-cli2 against all .md files in the projectnode_modules directoryExample output:
docs/setup-guide.md:45:1 MD022/blanks-around-headings Headings should be surrounded by blank lines
README.md:12:81 MD009/no-trailing-spaces Trailing spaces
With npx:
npx markdownlint-cli2 "**/*.md" --fix
With npm scripts (if configured):
npm run lint:md:fix
What this does:
Fixable issues include:
Non-fixable issues require intelligent analysis and manual fixes:
When "unfixable" errors remain after auto-fix, automatically analyze and fix them.
For detailed strategies on handling each error type, see the dedicated guide:
This guide covers:
Quick summary:
npx markdownlint-cli2 "**/*.md" --fixFor VS Code integration, see the dedicated guide:
The VS Code extension (davidanson.vscode-markdownlint) provides real-time linting in your editor. The guide covers:
This is optional but highly recommended for regular markdown work.
For CI/CD integration, see the dedicated guide:
GitHub Actions Configuration Guide
GitHub Actions can automatically validate markdown files on PRs and pushes. The guide covers:
This is optional but highly recommended for team projects.
WARNING: Only modify with explicit approval per policy above.
For detailed rule information, see the comprehensive guide:
The rules reference covers:
Quick syntax reminder:
{
"default": true, // Enable all defaults
"MD013": false, // Disable specific rule
"MD033": { // Configure with options
"allowed_elements": ["br"]
}
}
Common issues and solutions:
Solution: Run npm install or use npx: npx markdownlint-cli2 "**/*.md"
Solution:
npx markdownlint-cli2 "**/*.md" --fixFor detailed troubleshooting, see the dedicated guides:
Solution: Check Markdownlint Rules Reference for rule explanations, examples, and official documentation links.
For comprehensive best practices on markdown linting, configuration management, collaboration, and skill automation:
The guide covers:
These files should be created in your project root (see installation guides for setup):
.markdownlint-cli2.jsonc (required for custom rules)package.json (optional, for npm run commands).vscode/settings.json (optional, for auto-fix on save).github/workflows/markdown-lint.yml (optional, for CI/CD)This skill includes reference documentation in the references/ directory:
These scenarios are used to evaluate skill activation, guidance quality, and multi-model compatibility.
{
"name": "First-time setup",
"query": "I need to set up markdown linting in my project",
"context": "User has no existing markdown linting configuration",
"files": [],
"expected_behavior": [
"Skill activates successfully",
"Loads references/installation-setup.md for comprehensive guidance",
"Provides step-by-step installation instructions",
"Distinguishes between npx (zero-setup) and local install approaches",
"Guides through .markdownlint-cli2.jsonc configuration",
"Includes verification steps"
],
"test_models": ["sonnet", "haiku", "opus"]
}
{
"name": "Fix linting errors",
"query": "I'm getting MD022 errors, how do I fix them?",
"context": "User has linting errors and needs guidance on fixes",
"files": ["sample-file.md"],
"expected_behavior": [
"Skill activates for error type and rule explanation",
"Explains MD022 rule (blanks around headings)",
"Provides auto-fix command (npx markdownlint-cli2 --fix)",
"Explains both automatic and intelligent fix approaches",
"References intelligent-fixing-guide.md if needed",
"Provides verification steps"
],
"test_models": ["sonnet", "haiku", "opus"]
}
{
"name": "VS Code integration",
"query": "How do I enable auto-fix on save in VS Code?",
"context": "User wants to integrate markdown linting into their editor workflow",
"files": [],
"expected_behavior": [
"Skill activates for VS Code integration",
"Loads references/vscode-extension-setup.md",
"Provides extension installation instructions",
"Explains auto-fix configuration in .vscode/settings.json",
"Documents keyboard shortcuts and interactive features",
"Includes troubleshooting for common VS Code issues"
],
"test_models": ["sonnet", "haiku", "opus"]
}
{
"name": "GitHub Actions CI setup",
"query": "Add markdown linting to GitHub Actions",
"context": "User wants to automate markdown validation in CI/CD pipeline",
"files": [".github/workflows/"],
"expected_behavior": [
"Skill activates for GitHub Actions integration",
"Loads references/github-actions-config.md",
"Provides complete workflow file configuration",
"Explains trigger setup (PR and push events)",
"Documents workflow execution and results interpretation",
"Includes configuration for auto-fix and branch protection"
],
"test_models": ["sonnet", "haiku", "opus"]
}
{
"name": "Configuration customization",
"query": "How do I disable MD013 line length rule?",
"context": "User needs to customize linting rules for their project",
"files": [".markdownlint-cli2.jsonc"],
"expected_behavior": [
"Skill activates for rule customization",
"Explains configuration policy (fix content, not rules)",
"Provides .markdownlint-cli2.jsonc configuration example",
"Shows syntax for disabling/configuring specific rules",
"References references/markdownlint-rules.md for rule details",
"Emphasizes verification of changes across all tools"
],
"test_models": ["sonnet", "haiku", "opus"]
}
Tested with:
Observations: Skill's explicit command examples and clear decision trees should work well across all model tiers.
.claude/memory/workflows.mdDate: 2025-11-30 Model: claude-opus-4-5-20251101