Skip to content
My Learning Curve

Markdownlint

What is Markdownlint?

Section titled “What is Markdownlint?”

Markdownlint is a linter that analyzes Markdown files to enforce consistent style and catch common errors. It helps maintain high-quality documentation across your project.

See the official documentation.

Installation

Section titled “Installation”
Terminal window
npm i -D markdownlint-cli2 markdownlint-cli2-formatter-pretty

Configuration

Section titled “Configuration”

markdownlint-cli2 supports two types of configuration files:

.markdownlint-cli2.jsonc (CLI configuration)

Section titled “.markdownlint-cli2.jsonc (CLI configuration)”

This file configures the CLI tool itself (globs, ignores, gitignore support, etc.):

{
  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/main/schema/markdownlint-cli2-config-schema.json",
  "gitignore": true,
  "globs": ["**/*.{md,mdx}"],
  "ignores": ["**/node_modules", "**/.astro", "**/dist"],
}

.markdownlint.jsonc (Rules configuration)

Section titled “.markdownlint.jsonc (Rules configuration)”

This file configures the linting rules themselves:

{
  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
  "default": true,
  "MD013": false, // Disable line length limit
  "MD033": {
    // Allow specific HTML elements
    "allowed_elements": ["PackageManagers", "details", "summary"],
  },
  "MD041": false, // Allow frontmatter before first heading
}

Usage

Section titled “Usage”

Scripts

Section titled “Scripts”
// The globs are configured in `.markdownlint-cli2.jsonc`.
  "scripts": {
    "lint:md": "markdownlint-cli2",
    "lint:md:fix": "markdownlint-cli2 --fix"
  }
}

Running Manually

Section titled “Running Manually”

Check all markdown files:

Terminal window
pnpm run lint:md

Fix issues automatically:

Terminal window
pnpm run lint:md:fix

Integration with Lint-Staged

Section titled “Integration with Lint-Staged”

Add markdownlint to your .lintstagedrc.json:

{
  "*.{md,mdx}": ["markdownlint-cli2 --fix"]
}

This ensures markdown files are linted before each commit.

Common Rules

Section titled “Common Rules”

MD001 - Heading levels increment by one

Section titled “MD001 - Heading levels increment by one”
# Heading 1


## Heading 2 ✓


#### Heading 4 ✗ (skipped level 3)

MD012 - Multiple consecutive blank lines

Section titled “MD012 - Multiple consecutive blank lines”
Line 1


Line 2 ✓


Line 3 ✗ (too many blank lines above)

MD040 - Fenced code blocks should have a language

Section titled “MD040 - Fenced code blocks should have a language”
\`\`\`javascript ✓
const x = 1;
\`\`\`


\`\`\` ✗ (missing language)
code here
\`\`\`

VS Code Integration

Section titled “VS Code Integration”

Install the markdownlint extension for real-time linting in VS Code.

Add to .vscode/settings.json:

{
  "markdownlint.config": {
    "default": true
  }
}

Best Practices

Section titled “Best Practices”
  1. Run before committing: Use with lint-staged to catch issues early
  2. Configure for your needs: Disable rules that don’t fit your documentation style
  3. Use auto-fix: Many issues can be fixed automatically with --fix
  4. Document exceptions: Use inline comments for intentional rule violations

Inline Rule Configuration

Section titled “Inline Rule Configuration”

Disable rules for specific lines:

<!-- markdownlint-disable MD033 -->


<custom-element>Allowed HTML</custom-element>


<!-- markdownlint-enable MD033 -->

Resources

Section titled “Resources”