Markdownlint

Lint Markdown files for style and consistency using markdownlint via the markdownlint-cli2 CLI.

Running the linter

Lint specific files or directories:

npx markdownlint-cli2 "docs/**/*.md"

Lint and auto-fix fixable issues:

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

Lint multiple paths:

npx markdownlint-cli2 "docs/**/*.md" "README.md" "CHANGELOG.md"

Exclude paths with # (negation):

npx markdownlint-cli2 "**/*.md" "#node_modules"

Exit codes

• 0: No errors (warnings may exist)
• 1: Linting errors found
• 2: Linting failed (e.g., bad config)

Interpreting output

Output format: filepath:line rule/alias description

Example:

docs/guide.md:15 MD022/blanks-around-headings [Expected: 1; Actual: 0; Below]
docs/guide.md:42 MD034/no-bare-urls Bare URL used [Context: "..."]

Configuration

Project config file .markdownlint.json

{
  "default": true,
  "MD013": false,
  "MD033": { "allowed_elements": ["details", "summary", "br"] },
  "MD024": { "siblings_only": true }
}

Rules can be set to:

• true or "error" — enable as error
• "warning" — enable as warning
• false — disable
• { ... } — enable with parameters

CLI config file .markdownlint-cli2.jsonc

Controls both rules and CLI behavior:

{
  "config": {
    "default": true,
    "MD013": false
  },
  "globs": ["**/*.md"],
  "ignores": ["node_modules/**", "build/**"],
  "fix": false
}

Configuration precedence

1. .markdownlint-cli2.jsonc / .markdownlint-cli2.yaml (full CLI config)
2. .markdownlint.jsonc / .markdownlint.json / .markdownlint.yaml (rules only)
3. Inline HTML comment directives in the file itself

Inline directives

Control rules within a file using HTML comments:

<!-- markdownlint-disable MD013 -->
This long line won't trigger a warning because MD013 is disabled for this section of the file.
<!-- markdownlint-enable MD013 -->

<!-- markdownlint-disable-line MD034 -->
https://bare-url-allowed-on-this-line.com

<!-- markdownlint-disable-next-line MD041 -->
Not a heading on line 1

<!-- markdownlint-configure-file { "MD013": { "line_length": 120 } } -->

State capture/restore:

<!-- markdownlint-capture -->
<!-- markdownlint-disable MD013 -->
Long content here...
<!-- markdownlint-restore -->

Common rules quick reference

Rule	Alias	What it checks	Fixable
MD001	heading-increment	Heading levels increment by one	No
MD003	heading-style	Consistent heading style (atx vs setext)	No
MD004	ul-style	Consistent unordered list markers	Yes
MD005	list-indent	Consistent list indentation	Yes
MD007	ul-indent	Unordered list indentation depth	Yes
MD009	no-trailing-spaces	No trailing whitespace	Yes
MD010	no-hard-tabs	No hard tab characters	Yes
MD012	no-multiple-blanks	No consecutive blank lines	Yes
MD013	line-length	Line length limit (default 80)	No
MD022	blanks-around-headings	Blank lines around headings	Yes
MD023	heading-start-left	Headings must start at line beginning	Yes
MD025	single-h1	Only one top-level heading per file	No
MD031	blanks-around-fences	Blank lines around fenced code blocks	Yes
MD032	blanks-around-lists	Blank lines around lists	Yes
MD033	no-inline-html	No inline HTML	No
MD034	no-bare-urls	No bare URLs	No
MD040	fenced-code-language	Fenced code blocks need a language	No
MD041	first-line-h1	First line should be a top-level heading	No
MD047	single-trailing-newline	Files end with a single newline	Yes

For a complete reference of all 47 rules with parameters, see references/rules.md.

Workflow

When creating or editing markdown files:

1. Write or edit the markdown content
2. Run the linter: npx markdownlint-cli2 "path/to/file.md"
3. If errors are found:
   • Try auto-fix first: npx markdownlint-cli2 --fix "path/to/file.md"
   • Manually fix any remaining non-fixable issues
   • Re-run the linter to confirm zero errors
4. If a rule should be permanently disabled, update .markdownlint.json
5. For one-off exceptions, use inline directives

Tips

• Run --fix before manual fixes to save effort — about half the rules are auto-fixable
• Use rule aliases (e.g., no-trailing-spaces) instead of codes (e.g., MD009) in inline directives for readability
• The MD013 line-length rule is commonly disabled in projects (this project disables it in .markdownlint.json)
• Use <!-- markdownlint-disable-next-line --> for single-line exceptions rather than disable/enable blocks
• Configuration in .markdownlint.json applies to the directory and all subdirectories