markdownlint

0.40.0 verified Fri May 01 auth: no javascript

A Node.js style checker and lint tool for Markdown/CommonMark files. Current stable version is 0.40.0, released with a history of regular updates. It uses the micromark parser and honors the CommonMark specification, also supporting GFM syntax like autolinks and tables, as well as directives, footnotes, and math via micromark extensions. Unlike other Markdown linters, it provides a comprehensive library of rules and is designed for programmatic use in Node.js projects, with multiple CLI wrappers and editor integrations.

Common errors

error Cannot find module 'markdownlint' ↓

cause Package not installed or used with require() in ESM-only version

fix

Install with npm: npm install markdownlint --save-dev. Use import statement instead of require().

error TypeError: markdownlint.sync is not a function ↓

cause Using deprecated synchronous API, or importing wrong shape

fix

Use import { lintSync } from 'markdownlint' instead of markdownlint.sync.

error Invalid configuration: 'default' must be a boolean ↓

cause Setting config.default to a non-boolean value like 'true' (string) or an object

fix

Set config.default as a boolean true or false, not a string. Example: default: true

error Error: Cannot find module 'micromark' ↓

cause markdownlint has a peer dependency on micromark that is missing

fix

Install micromark as a dependency: npm install micromark

Warnings

breaking ESM-only since v0.34.0, synchronous API removed in v0.26.0 ↓

fix Use import syntax instead of require(). Use lintSync named export for synchronous usage.

deprecated The markdownlint.sync function is deprecated since v0.26.0 ↓

fix Use the lintSync named export instead.

gotcha Configuration files (like .markdownlint.json) are not automatically loaded when using the API programmatically ↓

fix Manually load and pass the config option object to the lint function.

gotcha Rule MD024 (multiple headings with same content) by default only checks siblings, not all headings ↓

fix Set allow_different_nesting: false in config to check all headings.

Install

npm install markdownlint

yarn add markdownlint

pnpm add markdownlint

Imports

markdownlint

wrong

const markdownlint = require('markdownlint')

correct

import markdownlint from 'markdownlint'

Package is ESM-only since v0.34.0. Use import statement.

lint
```
import { lint } from 'markdownlint'
```
Main function exported as named export. Also available as default import.
LintResults
wrong
```
import { LintResults } from 'markdownlint'
```
correct
```
import type { LintResults } from 'markdownlint'
```
LintResults is a TypeScript type, not a runtime value. Import using 'import type'.
markdownlint.sync
wrong
```
const { sync } = require('markdownlint')
```
correct
```
import { lintSync } from 'markdownlint'
```
Synchronous linting is available as a separate named export lintSync since v0.26.0.

Quickstart

Lint a Markdown file with custom configuration and log errors.

import { lint } from 'markdownlint';
import { readFileSync } from 'fs';

const options = {
  strings: {
    'example.md': readFileSync('example.md', 'utf8'),
  },
  config: {
    default: true,
    MD013: { line_length: 80 },
  },
};

lint(options, (err, results) => {
  if (err) {
    console.error(err);
    return;
  }
  for (const file in results) {
    const errors = results[file];
    errors.forEach((error) => {
      console.log(`${file}:${error.lineNumber}: ${error.ruleName} - ${error.ruleDescription}`);
    });
  }
});