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):