eslint-plugin-markdownlint

ESLint plugin that runs markdownlint rules on Markdown files.

Install

npm install eslint-plugin-markdownlint --save-dev

Usage

Flat config (ESLint ≥9)

// eslint.config.js
import markdownlint from "eslint-plugin-markdownlint";
import markdownlintParser from "eslint-plugin-markdownlint/parser.js";

export default [
  {
    files: ["**/*.md"],
    plugins: { markdownlint },
    languageOptions: { parser: markdownlintParser },
    rules: {
      ...markdownlint.configs.recommended.rules,
    },
  },
];

Legacy .eslintrc

{
  "overrides": [
    {
      "files": ["*.md"],
      "parser": "eslint-plugin-markdownlint/parser",
      "extends": ["plugin:markdownlint/recommended"]
    }
  ]
}

Configuring rules

All rules accept an options object matching the corresponding markdownlint rule parameters. For example:

rules: {
  "markdownlint/md013": ["error", { line_length: 100, code_blocks: false }],
  "markdownlint/md033": ["error", { allowed_elements: ["br", "details"] }],
  "markdownlint/md025": "off",
}

See markdownlint rules documentation for the full list of available options per rule.

Config file integration

The plugin automatically reads the nearest .markdownlint.json or .markdownlint.jsonc file, walking up from the linted file's directory. This is the same file the vscode-markdownlint extension reads, so you can share configuration between the editor and ESLint without duplication.

Rule options in your ESLint config always take precedence over the config file.

Custom config file location

If your config file is in a non-standard location, point to it via ESLint settings:

// eslint.config.js
export default [
  {
    files: ["**/*.md"],
    plugins: { markdownlint },
    languageOptions: { parser: markdownlintParser },
    settings: {
      markdownlint: { configFile: ".config/.markdownlint.json" },
    },
    rules: markdownlint.configs.recommended.rules,
  },
];

The path is resolved relative to the current working directory.

TypeScript

The package ships with type definitions. Rule option types are exported for use in typed ESLint configs:

import type { MD013Options, MD033Options } from "eslint-plugin-markdownlint";

The RuleOptionsMap type maps each rule name to its options interface, which is useful with typed flat config helpers.

Supported rules

All built-in markdownlint rules are supported (MD001–MD060, excluding the deprecated MD002 and MD006):

Rule	Description
MD001	Heading levels should only increment by one level at a time
MD003	Heading style
MD004	Unordered list style
MD005	Inconsistent indentation for list items at the same level
MD007	Unordered list indentation
MD009	Trailing spaces
MD010	Hard tabs
MD011	Reversed link syntax
MD012	Multiple consecutive blank lines
MD013	Line length
MD014	Dollar signs used before commands without showing output
MD018	No space after hash on atx style heading
MD019	Multiple spaces after hash on atx style heading
MD020	No space inside hashes on closed atx style heading
MD021	Multiple spaces inside hashes on closed atx style heading
MD022	Headings should be surrounded by blank lines
MD023	Headings must start at the beginning of the line
MD024	Multiple headings with the same content
MD025	Multiple top-level headings in the same document
MD026	Trailing punctuation in heading
MD027	Multiple spaces after blockquote symbol
MD028	Blank line inside blockquote
MD029	Ordered list item prefix
MD030	Spaces after list markers
MD031	Fenced code blocks should be surrounded by blank lines
MD032	Lists should be surrounded by blank lines
MD033	Inline HTML
MD034	Bare URL used
MD035	Horizontal rule style
MD036	Emphasis used instead of a heading
MD037	Spaces inside emphasis markers
MD038	Spaces inside code span elements
MD039	Spaces inside link text
MD040	Fenced code blocks should have a language specified
MD041	First line in a file should be a top-level heading
MD042	No empty links
MD043	Required heading structure
MD044	Proper names should have the correct capitalization
MD045	Images should have alternate text (alt text)
MD046	Code block style
MD047	Files should end with a single newline character
MD048	Code fence style
MD049	Emphasis style
MD050	Strong style
MD051	Link fragments should be valid
MD052	Reference links and images should use a label that is defined
MD053	Link and image reference definitions should be needed
MD054	Link and image style
MD055	Table pipe style
MD056	Table column count
MD058	Tables should be surrounded by blank lines
MD059	Link text should be descriptive
MD060	Table column style

Markdownlint documentation

For full rule documentation refer to DavidAnson/markdownlint.