Skip to content

CowboyLogic/ai-dev / skills/markdownlint-validator

markdownlint-validator

Unverified

Guide for identifying and fixing markdownlint violations in Markdown files. Use this skill whenever asked to fix markdown linting errors, validate markdown files, resolve markdownlint violations, clean up markdown formatting issues, enforce markdown style rules, or correct any MD### rule failures. Always load this skill when working with .markdownlint config files or markdownlint-cli output.

Markdownlint Validator

This skill covers identifying, fixing, and preventing markdownlint rule violations across Markdown files. It targets the DavidAnson/markdownlint rule set (v0.x), used by VS Code, markdownlint-cli, and markdownlint-cli2.

Quick Decision Guide

TaskLoad
Look up a specific rule (MD###), its parameters, or edge casesreferences/rules.md
Configure .markdownlint.json, disable rules, inline suppressionreferences/config.md
Run linting against files in bulkscripts/validate.sh

Always read the relevant reference file before fixing non-trivial violations.

Core Workflow

1. Get the violations

# Install markdownlint-cli if not present
npm install -g markdownlint-cli

# Lint files (outputs rule ID, file, line, description)
markdownlint "docs/**/*.md"

# Or use the validate script
bash scripts/validate.sh docs/

2. Triage

  • Group violations by rule ID (e.g., all MD022 together).
  • Check if the rule is auto-fixable (marked ✓ in references/rules.md) — fix those first with markdownlint --fix.
  • Fix non-auto-fixable violations manually, one rule at a time.

3. Auto-fix what you can

markdownlint --fix "docs/**/*.md"

Auto-fixable rules include: MD004, MD005, MD007, MD009, MD010, MD011, MD012, MD014, MD018–MD021, MD023, MD026, MD029, MD030, MD031, MD032, MD034, MD037–MD039, MD044, MD047, MD053, MD054, MD058.

4. Fix remaining violations manually

Read references/rules.md for the relevant rule's description and fix pattern. The most common manual fixes are listed below.

5. Re-validate

markdownlint "docs/**/*.md"

Zero output = clean.


Common Violations — Quick Fix

RuleViolationFix
MD009Trailing spacesRemove trailing whitespace from each line
MD010Hard tabsReplace \t with spaces (usually 2 or 4)
MD012Multiple consecutive blank linesCollapse to one blank line
MD013Line too long (>80 chars)Wrap text; or disable/configure the rule for long URLs
MD022Heading not surrounded by blank linesAdd blank line before and after every heading
MD031Fenced code block not surrounded by blank linesAdd blank line before ``` and after ```
MD032List not surrounded by blank linesAdd blank line before and after every list block
MD040Fenced code block missing languageAdd language tag: ```bash, ```python, ```text
MD041First line is not an H1Add # Title as first line, or disable if file is a fragment
MD047File does not end with newlineAdd a trailing newline at end of file
MD051Broken link fragment (#anchor)Match fragment exactly to heading text (lowercase, hyphens)
MD058Table not surrounded by blank linesAdd blank line before and after every table

Heading fragment format (MD051)

GitHub heading algorithm: lowercase, remove punctuation, spaces → hyphens, append -N if duplicate.

## My Heading (2026)    →  #my-heading-2026
## API Reference        →  #api-reference
## API Reference        →  #api-reference-1  (duplicate)

Inline Suppression

When a violation is intentional and cannot be restructured:

<!-- markdownlint-disable MD013 -->
This line is intentionally very long because it contains a URL that cannot be split.
<!-- markdownlint-enable MD013 -->

<!-- markdownlint-disable-next-line MD033 -->
<details><summary>Click to expand</summary>

For file-wide suppression, use front matter or .markdownlint.json. See references/config.md.


Debugging Checklist

SymptomCheck
Violations persist after --fixRule is not auto-fixable; fix manually
MD013 fires on URLsSet "line-length": { "line_length": 120 } or use strict: false
MD041 fires on partial/fragment filesDisable: "first-line-heading": false in config
MD033 fires on intentional HTMLAdd to allowed_elements in config
Violations only in certain directoriesUse .markdownlint.json in that subdirectory
Rule not in this skill's tablesCheck references/rules.md for full rule list
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall