markdownlint-compliance

name	markdownlint-compliance
description	>- Use when this capability is needed.

Markdownlint Compliance

Config Resolution

markdownlint checks for config in this order (first match wins):

1. markdownlint.config in VS Code / Cursor settings
2. .markdownlint.jsonc in the workspace root
3. .markdownlint.json in the workspace root
4. .markdownlint.yaml / .markdownlint.yml in the workspace root
5. Built-in defaults (all rules enabled)

Before writing markdown, check if a config exists:

ls .markdownlint* 2>/dev/null || echo "no config — using defaults"

If no config exists, all rules are enabled with their default settings.

Rules the AI Commonly Violates

These are the rules most frequently broken by AI-generated markdown, ordered by frequency:

MD031 — Blank lines around fenced code blocks

Fenced code blocks must have a blank line before the opening fence and after the closing fence.

<!-- ❌ BAD -->
Some text:
```bash
echo "hello"
```
More text.

<!-- ✅ GOOD -->
Some text:

```bash
echo "hello"
```

More text.

MD032 — Blank lines around lists

Lists need a blank line before the first item and after the last item.

<!-- ❌ BAD -->
Some text:
- Item one
- Item two
More text.

<!-- ✅ GOOD -->
Some text:

- Item one
- Item two

More text.

MD040 — Fenced code blocks should have a language specified

Every fenced code block needs a language identifier after the opening triple backticks.

Common language tags: bash, json, yaml, markdown, typescript, python, tsx, css, html, sql, nix, toml, diff, text, plaintext.

Use text or plaintext if no language applies. Use markdown for markdown examples.

MD034 — No bare URLs

URLs in prose must be wrapped — either as links or angle brackets.

<!-- ❌ BAD -->
See https://example.com for details.

<!-- ✅ GOOD -->
See <https://example.com> for details.
See [the docs](https://example.com) for details.

MD060 — Table column style

Table pipes must be consistently styled. Use the "compact" style (single space padding):

<!-- ✅ Compact style (consistent) -->
| Name | Value |
| ---- | ----- |
| foo  | bar   |

MD001 — Heading levels increment by one

Don't skip heading levels (e.g., ## followed by ####).

<!-- ❌ BAD -->
## Section
#### Subsection

<!-- ✅ GOOD -->
## Section
### Subsection

Full Rule Quick Reference

Rule	Name	Default	Summary
MD001	heading-increment	on	Headings increment by one level
MD003	heading-style	atx	Use # style headings
MD004	ul-style	consistent	Consistent list marker
MD005	list-indent	on	Consistent list indentation
MD009	no-trailing-spaces	on	No trailing whitespace
MD010	no-hard-tabs	on	No hard tab characters
MD012	no-multiple-blanks	on	No consecutive blank lines
MD013	line-length	80 (often off)	Line length limit
MD018	no-missing-space-atx	on	Space after # in headings
MD019	no-multiple-space-atx	on	No multiple spaces after #
MD022	blanks-around-headings	on	Blank lines around headings
MD023	heading-start-left	on	Headings at start of line
MD024	no-duplicate-heading	on	No duplicate heading text
MD025	single-title	on	Only one # (H1) per document
MD027	no-multiple-space-blockquote	on	No multiple spaces after >
MD028	no-blanks-blockquote	on	No blank lines in blockquotes
MD029	ol-prefix	one_or_ordered	Ordered list prefix style
MD030	list-marker-space	on	Spaces after list markers
MD031	blanks-around-fences	on	Blank lines around code blocks
MD032	blanks-around-lists

Auto-Fix with markdownlint-cli2

markdownlint-cli2 --fix automatically resolves most whitespace and formatting violations. Always run it before attempting manual fixes.

Usage

# Single file
npx markdownlint-cli2 "path/to/file.md" --fix

# Directory (glob pattern)
npx markdownlint-cli2 "docs/**/*.md" --fix

# Multiple specific files
npx markdownlint-cli2 "README.md" ".cursor/rules/*.mdc" --fix

# Entire workspace (careful — respects .markdownlintignore)
npx markdownlint-cli2 "**/*.md" --fix

What --fix Resolves Automatically

Rule	Description
MD009	Trailing spaces
MD010	Hard tabs
MD012	Multiple consecutive blank lines
MD022	Missing blank lines around headings
MD023	Heading not at start of line
MD027	Multiple spaces after blockquote
MD030	Spaces after list markers
MD031	Missing blank lines around code blocks
MD032	Missing blank lines around lists
MD047	Missing single trailing newline

What --fix Cannot Resolve (Manual Only)

Rule	Description	How to Fix
MD013	Line length	Reflow text or disable rule
MD034	Bare URLs	Wrap in <url> or [text](url)
MD036	Emphasis as heading	Replace **text** with ### text
MD040	Missing fence language	Add tag after opening triple fences
MD041	No first-line heading	Add # Title as the first line

Recommended Workflow

1. Run --fix             (~60% of issues resolved automatically)
2. Re-lint               (only manual-fix rules should remain)
3. Fix manually          (line length, bare URLs, language tags)
4. Run ReadLints         (should be clean)

Example Session

# Step 1: Auto-fix
npx markdownlint-cli2 ".cursor/rules/*.mdc" --fix

# Step 2: See what's left
npx markdownlint-cli2 ".cursor/rules/*.mdc"
# Output: only MD013, MD040, MD036 remain

# Step 3: Fix those manually using StrReplace or editor

Configuration for --fix

Create .markdownlint-cli2.jsonc in the workspace root to customize:

{
  // Disable rules that don't apply to your project
  "config": {
    "MD013": false,
    "MD033": false
  },
  // Ignore certain paths
  "ignores": ["node_modules/**", "**/content/blog/**"]
}

Workflow

1. Before writing: Check for workspace .markdownlint* config
2. While writing: Follow the rules above (blank lines around fences/lists, language tags, no bare URLs)
3. After writing: Run npx markdownlint-cli2 "file.md" --fix
4. Verify: Run ReadLints on the file for remaining violations
5. Fix remaining: Manually fix what --fix couldn't resolve
6. Scope: Only fix lints you introduced — don't fix pre-existing ones unless editing that section

---

Source: cdbattags/ai — distributed by TomeVault.