eslint-plugin-markdownlint

0.9.0 verified Sat Apr 25 auth: no javascript

ESLint plugin that integrates markdownlint (v0.9.0) as ESLint rules for linting Markdown files. It uses a custom parser to parse Markdown and applies markdownlint rules (mdXXX codes) within ESLint. The plugin supports both flat configs (ESLint >=9) and legacy .eslintrc overrides. It is actively maintained with monthly releases, but has known limitations: no support for .mdlrc config files or rule aliases (only mdXXX codes), and no plans for tag-based rule selection. It requires ESLint >=7.5.0 as a peer dependency.

Common errors

error ESLint: Error: Failed to load parser 'eslint-plugin-markdownlint/parser' declared in 'parser' field: Module not found ↓

cause Missing required peer dependency or incorrect installation.

fix

Run npm install eslint-plugin-markdownlint --save-dev to install the plugin and its parser.

error Error: Cannot find module 'eslint-plugin-markdownlint/parser' ↓

cause Import path for parser is incorrect or module is not installed.

fix

Ensure the package is installed and import path is correct: import from 'eslint-plugin-markdownlint/parser'.

error Configuration for rule 'markdownlint/md001' is invalid: Expected object with optional properties 'level', 'arguments', ... ↓

cause Rule configuration format is incorrect; markdownlint rules expect specific options.

fix

Check markdownlint rule documentation for the correct option structure, e.g., \"md001\": [\"error\", { properties... }].

Warnings

breaking Flat config (ESLint >=9) requires ES module imports; CommonJS require will not work in eslint.config.js. ↓

fix Use `import` syntax and ensure package.json has \"type\": \"module\" or use .mjs extension.

deprecated Legacy .eslintrc config format is deprecated in ESLint >=9. Future versions may drop support. ↓

fix Migrate to eslint.config.js flat config.

gotcha Rule aliases (e.g., 'no-hard-tabs' for md010) are not supported. Only mdXXX codes work. ↓

fix Use rule codes like \"md010\" instead of descriptive names.

gotcha External config files (.mdlrc, .markdownlintrc) are not supported. All configuration must be done via ESLint rules. ↓

fix Configure all markdownlint rules in ESLint's rules section.

Install

npm install eslint-plugin-markdownlint

yarn add eslint-plugin-markdownlint

pnpm add eslint-plugin-markdownlint

Imports

markdownlintPlugin
wrong
```
const markdownlintPlugin = require('eslint-plugin-markdownlint')
```
correct
```
import markdownlintPlugin from 'eslint-plugin-markdownlint'
```
ESM import is required for flat configs. CommonJS require works in legacy configs but not recommended.

markdownlintParser

wrong

import markdownlintParser from 'eslint-plugin-markdownlint'

correct

import markdownlintParser from 'eslint-plugin-markdownlint/parser'

The parser is a separate export at the /parser subpath. Do not import it from the main entry.

plugin:markdownlint/recommended
wrong
```
extends: ['eslint-plugin-markdownlint/recommended']
```
correct
```
extends: ['plugin:markdownlint/recommended']
```
In legacy .eslintrc, use the plugin prefix 'plugin:markdownlint/recommended', not the full npm package name.

Quickstart

Shows how to set up eslint-plugin-markdownlint with flat config (ESLint >=9) and legacy .eslintrc.

// Install: npm install eslint-plugin-markdownlint --save-dev

// eslint.config.js (flat config, ESLint >=9)
import markdownlintPlugin from 'eslint-plugin-markdownlint';
import markdownlintParser from 'eslint-plugin-markdownlint/parser';

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

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