Markdown & MDX Formatting & Linting

Format and lint markdown and MDX files using markdownlint CLI tools with comprehensive understanding of all markdown rules.

Quick Start

Check if markdownlint is available

which markdownlint || which markdownlint

Install if needed

pnpm add -D markdownlint

or

npm install -g markdownlint

Auto-fix files (markdown and MDX)

markdownlint --fix "**/*.{md,mdx}"

Check specific files

markdownlint README.md docs//*.md content//*.mdx

Configuration Detection

Check for config files in this order:

• .markdownlint.json

• .markdownlint.jsonc

• .markdownlint.yaml

• .markdownlintrc

• markdownlint key in package.json

Common Workflow

• Detect environment: Check for markdownlint CLI

• Find config: Look for config files

• Run linter: Identify issues

• Apply fixes: Auto-fix or manual

• Verify: Re-run to confirm

Most Common Issues & Quick Fixes

Headings

• MD001: Heading levels increment (# → ## → ### not # → ###)

• MD018/MD019: Single space after hash (# Heading not #Heading )

• MD022: Blank lines around headings

• MD025: Single H1 per document

• MD041: First line should be H1

<!-- Good heading structure -->

Main Title

Section

Subsection

Content here...

Lists

• MD004: Consistent list markers (all - or all * )

• MD007: Nested lists indent 2 spaces

• MD030: Single space after list marker

• MD032: Blank lines around lists

<!-- Good list structure -->

• Item 1
  • Nested item
  • Another nested
• Item 2

Whitespace

• MD009: No trailing spaces

• MD010: Use spaces not tabs

• MD012: Single blank lines (not multiple)

• MD047: File ends with newline

Links & Images

• MD034: Wrap bare URLs in <> : <http://example.com>

• MD042: Links need text: Link Text not

• MD045: Images need alt text:

Code Blocks

• MD031: Blank lines around code blocks

• MD040: Specify language for code blocks

<!-- Good code block --> Text before

const code = 'here';

Text after

CLI Commands

Fix all markdown and MDX files

markdownlint --fix "**/*.{md,mdx}"

Fix specific files

markdownlint --fix README.md CHANGELOG.md content/blog.mdx

Check without fixing

markdownlint "**/*.{md,mdx}"

Use specific config

markdownlint --config .markdownlint.json "**/*.{md,mdx}"

Ignore specific rules

markdownlint --disable MD013 MD033 "**/*.{md,mdx}"

Output JSON for parsing

markdownlint --json "**/*.{md,mdx}"

Common Patterns

Fix Multiple Issues at Once

<!-- Before --> #Title Some text with trailing spaces Tab indented line

• Item 1

• Item 2 Visit http://example.com

<!-- After -->

Title

Some text with trailing spaces Space indented line

• Item 1
• Item 2

Visit <http://example.com>

Add to package.json

{ "scripts": { "lint:md": "markdownlint "/*.{md,mdx}" --ignore node_modules", "lint:md:fix": "markdownlint "/*.{md,mdx}" --ignore node_modules --fix" } }

Detailed Rules Reference

For comprehensive documentation of all markdown rules with examples and fixes, see rules-reference.md.

Resources

• markdownlint GitHub

• markdownlint Rules