ESLint Markdown Language Plugin

Lint JS, JSX, TypeScript, and more inside Markdown.

Usage

Installing

Install the plugin alongside ESLint v9 or greater:

npm install --save-dev eslint @eslint/markdown

Configurations

| Configuration Name | Description | |---------------|-----------------| | recommended | Lints all .md files with the recommended rules and assumes CommonMark format. | | processor | Enables extracting code blocks from all .md files so code blocks can be individually linted. |

In your eslint.config.js file, import @eslint/markdown and include the recommended config to enable the Markdown processor on all .md files:

// eslint.config.js
import markdown from "@eslint/markdown";

export default [
    ...markdown.configs.recommended

    // your other configs here
];

Rules

| Rule Name | Description | Recommended | | :- | :- | :-: | | fenced-code-language | Require languages for fenced code blocks. | yes | | heading-increment | Enforce heading levels increment by one. | yes | | no-duplicate-headings | Disallow duplicate headings in the same document. | no | | no-empty-links | Disallow empty links. | yes | | no-html | Disallow HTML tags. | no | | no-invalid-label-refs | Disallow invalid label references. | yes | | no-missing-label-refs | Disallow missing label references. | yes |

Note: This plugin does not provide formatting rules. We recommend using a source code formatter such as Prettier for that purpose.

In order to individually configure a rule in your eslint.config.js file, import @eslint/markdown and configure each rule with a prefix:

// eslint.config.js
import markdown from "@eslint/markdown";

export default [
    {
        files: ["**/*.md"],
        plugins: {
            markdown
        },
        language: "markdown/commonmark",
        rules: {
            "markdown/no-html": "error"
        }
    }
];

You can individually disable rules in Markdown using HTML comments, such as:

<!-- eslint-disable-next-line markdown/no-html -- I want to allow HTML here -->
<custom-element>Hello world!</custom-element>

<!-- eslint-disable markdown/no-html -- here too -->
<another-element>Goodbye world!</another-element>
<!-- eslint-enable markdown/no-html -- safe to re-enable now -->

[Object] <!-- eslint-disable-line markdown/no-missing-label-refs -- not meant to be a link ref -->

Languages

| Language Name | Description | |---------------|-----------------| | commonmark | Parse using CommonMark Markdown format | | gfm | Parse using GitHub-Flavored Markdown format |

In order to individually configure a language in your eslint.config.js file, import @eslint/markdown and configure a language:

// eslint.config.js
import markdown from "@eslint/markdown";

export default [
    {
        files: ["**/*.md"],
        plugins: {
            markdown
        },
        language: "markdown/gfm",
        rules: {
            "markdown/no-html": "error"
        }
    }
];

Processors

| Processor Name | Description | |---------------|-----------------| | markdown | Extract fenced code blocks from the Markdown code so they can be linted separately. |

Editor Integrations

VSCode

vscode-eslint has built-in support for the Markdown processor.

Atom

The linter-eslint package allows for linting within the Atom IDE.

In order to see @eslint/markdown work its magic within Markdown code blocks in your Atom editor, you can go to linter-eslint's settings and within "List of scopes to run ESLint on...", add the cursor scope "source.gfm".

However, this reports a problem when viewing Markdown which does not have configuration, so you may wish to use the cursor scope "source.embedded.js", but note that @eslint/markdown configuration comments and skip directives won't work in this context.

Contributing

$ git clone https://github.com/eslint/markdown.git
$ cd markdown
$ npm install
$ npm test

This project follows the ESLint contribution guidelines.

Sponsors

The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. Become a Sponsor to get your logo on our READMEs and website.