Awesome

ESLint Markdown Language Plugin

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

Usage

Installing

Install the plugin alongside ESLint v8 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
        },
        rules: {
            "markdown/no-html": "error"
        }
    }
];

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.