Cdbattags AI Markdownlint Compliance

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

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

What --fix Cannot Resolve (Manual Only)

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.