eslint-plugin-markdown

What is eslint-plugin-markdown?

The eslint-plugin-markdown package allows you to lint JavaScript code blocks within Markdown files using ESLint. This is particularly useful for ensuring that code snippets in documentation are up to standard and free of errors.

What are eslint-plugin-markdown's main functionalities?

Linting JavaScript Code Blocks in Markdown

This configuration allows ESLint to process JavaScript code blocks within Markdown files. By specifying the `markdown/markdown` processor, ESLint will recognize and lint the JavaScript code embedded in Markdown.

```json
{
  "overrides": [
    {
      "files": ["**/*.md"],
      "processor": "markdown/markdown"
    }
  ]
}
```

Custom ESLint Rules for Markdown

This configuration applies custom ESLint rules specifically to JavaScript code blocks within Markdown files. In this example, the `no-console` rule is enforced, which will trigger an error if `console` statements are found in the code blocks.

```json
{
  "overrides": [
    {
      "files": ["**/*.md/*.js"],
      "rules": {
        "no-console": "error"
      }
    }
  ]
}
```

Linting Specific Code Blocks

This configuration allows you to lint only specific code blocks within a Markdown file. By defining the `start` and `end` markers, you can control which parts of the Markdown file are subject to linting.

```json
{
  "overrides": [
    {
      "files": ["**/*.md"],
      "processor": "markdown/markdown",
      "settings": {
        "markdown/code-blocks": [
          {
            "language": "js",
            "start": "<!-- eslint-enable -->",
            "end": "<!-- eslint-disable -->"
          }
        ]
      }
    }
  ]
}
```

Other packages similar to eslint-plugin-markdown

remark-lint

remark-lint is a plugin for remark, a Markdown processor powered by plugins. It provides a set of rules to lint Markdown files, ensuring consistency and quality. Unlike eslint-plugin-markdown, which focuses on linting JavaScript code within Markdown, remark-lint is designed to lint the Markdown content itself.

markdownlint

markdownlint is a Node.js style checker and lint tool for Markdown files. It provides a set of rules to enforce consistent Markdown style and formatting. While eslint-plugin-markdown focuses on JavaScript code within Markdown, markdownlint is dedicated to the Markdown syntax and structure.

markdown-it

markdown-it is a Markdown parser that can be extended with plugins to add custom functionality. While it is not a linter, it can be used in conjunction with other tools to process and validate Markdown content. It is more flexible and general-purpose compared to eslint-plugin-markdown, which is specifically for linting JavaScript code in Markdown.

README

eslint-plugin-markdown

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

Usage

Installing

Install the plugin alongside ESLint v8 or greater:

npm install --save-dev eslint eslint-plugin-markdown

Configuring

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

// eslint.config.js
import markdown from "eslint-plugin-markdown";

export default [
    ...markdown.configs.recommended

    // your other configs here
];

If you are still using the deprecated .eslintrc.js file format for ESLint, you can extend the plugin:markdown/recommended-legacy config to enable the Markdown processor on all .md files:

// .eslintrc.js
module.exports = {
    extends: "plugin:markdown/recommended-legacy"
};

Advanced Configuration

You can manually include the Markdown processor by setting the processor option in your configuration file for all .md files.

Each fenced code block inside a Markdown document has a virtual filename appended to the Markdown file's path.

The virtual filename's extension will match the fenced code block's syntax tag, except for the following:

• javascript and ecmascript are mapped to js
• typescript is mapped to ts
• markdown is mapped to md

For example, ```js code blocks in README.md would match README.md/*.js and ```typescript in CONTRIBUTING.md would match CONTRIBUTING.md/*.ts.

You can use glob patterns for these virtual filenames to customize configuration for code blocks without affecting regular code. For more information on configuring processors, refer to the ESLint documentation.

Here's an example:

// eslint.config.js
import markdown from "eslint-plugin-markdown";

export default [
    {
        // 1. Add the plugin
        plugins: {
            markdown
        }
    },
    {
        // 2. Enable the Markdown processor for all .md files.
        files: ["**/*.md"],
        processor: "markdown/markdown"
    },
    {
        // 3. Optionally, customize the configuration ESLint uses for ```js
        // fenced code blocks inside .md files.
        files: ["**/*.md/*.js"],
        // ...
        rules: {
            // ...
        }
    }

    // your other configs here
];

In the deprecated .eslintrc.js format:

// .eslintrc.js
module.exports = {
    // 1. Add the plugin.
    plugins: ["markdown"],
    overrides: [
        {
            // 2. Enable the Markdown processor for all .md files.
            files: ["**/*.md"],
            processor: "markdown/markdown"
        },
        {
            // 3. Optionally, customize the configuration ESLint uses for ```js
            // fenced code blocks inside .md files.
            files: ["**/*.md/*.js"],
            // ...
            rules: {
                // ...
            }
        }
    ]
};

Frequently-Disabled Rules

Some rules that catch mistakes in regular code are less helpful in documentation. For example, no-undef would flag variables that are declared outside of a code snippet because they aren't relevant to the example. The markdown.configs.recommended config disables these rules in Markdown files:

• no-undef
• no-unused-expressions
• no-unused-vars
• padded-blocks

Use glob patterns to disable more rules just for Markdown code blocks:

// / eslint.config.js
import markdown from "eslint-plugin-markdown";

export default [
    {
        plugins: {
            markdown
        }
    },
    {
        files: ["**/*.md"],
        processor: "markdown/markdown"
    },
    {
        // 1. Target ```js code blocks in .md files.
        files: ["**/*.md/*.js"],
        rules: {
            // 2. Disable other rules.
            "no-console": "off",
            "import/no-unresolved": "off"
        }
    }

    // your other configs here
];

And in the deprecated .eslintrc.js format:

// .eslintrc.js
module.exports = {
    plugins: ["markdown"],
    overrides: [
        {
            files: ["**/*.md"],
            processor: "markdown/markdown"
        },
        {
            // 1. Target ```js code blocks in .md files.
            files: ["**/*.md/*.js"],
            rules: {
                // 2. Disable other rules.
                "no-console": "off",
                "import/no-unresolved": "off"
            }
        }
    ]
};

Strict Mode

"use strict" directives in every code block would be annoying. The markdown.configs.recommended config enables the impliedStrict parser option and disables the strict rule in Markdown files. This opts into strict mode parsing without repeated "use strict" directives.

Unsatisfiable Rules

Markdown code blocks are not real files, so ESLint's file-format rules do not apply. The markdown.configs.recommended config disables these rules in Markdown files:

• eol-last: The Markdown parser trims trailing newlines from code blocks.
• unicode-bom: Markdown code blocks do not have Unicode Byte Order Marks.

Running

If you are using an eslint.config.js file, then you can run ESLint as usual and it will pick up file patterns in your config file. The --ext option is not available when using flat config.

If you are using an .eslintrc.* file, then you can run ESLint as usual and it will pick up file extensions specified in overrides[].files patterns in config files.

Autofixing

With this plugin, ESLint's --fix option can automatically fix some issues in your Markdown fenced code blocks. To enable this, pass the --fix flag when you run ESLint:

eslint --fix .

What Gets Linted?

With this plugin, ESLint will lint fenced code blocks in your Markdown documents:

```js
// This gets linted
var answer = 6 * 7;
console.log(answer);
```

Here is some regular Markdown text that will be ignored.

```js
// This also gets linted

/* eslint quotes: [2, "double"] */

function hello() {
    console.log("Hello, world!");
}
hello();
```

```jsx
// This can be linted too if you add `.jsx` files to file patterns in the `eslint.config.js`.
// Or `overrides[].files` in `eslintrc.*`.
var div = <div className="jsx"></div>;
```

Blocks that don't specify a syntax are ignored:

```
This is plain text and doesn't get linted.
```

Unless a fenced code block's syntax appears as a file extension in file patterns in your config file, it will be ignored.

Configuration Comments

The processor will convert HTML comments immediately preceding a code block into JavaScript block comments and insert them at the beginning of the source code that it passes to ESLint. This permits configuring ESLint via configuration comments while keeping the configuration comments themselves hidden when the markdown is rendered. Comment bodies are passed through unmodified, so the plugin supports any configuration comments supported by ESLint itself.

This example enables the alert global variable, disables the no-alert rule, and configures the quotes rule to prefer single quotes:

<!-- global alert -->
<!-- eslint-disable no-alert -->
<!-- eslint quotes: ["error", "single"] -->

```js
alert('Hello, world!');
```

Each code block in a file is linted separately, so configuration comments apply only to the code block that immediately follows.

Assuming `no-alert` is enabled in `eslint.config.js`, the first code block will have no error from `no-alert`:

<!-- global alert -->
<!-- eslint-disable no-alert -->

```js
alert("Hello, world!");
```

But the next code block will have an error from `no-alert`:

<!-- global alert -->

```js
alert("Hello, world!");
```

Skipping Blocks

Sometimes it can be useful to have code blocks marked with js even though they don't contain valid JavaScript syntax, such as commented JSON blobs that need js syntax highlighting. Standard eslint-disable comments only silence rule reporting, but ESLint still reports any syntax errors it finds. In cases where a code block should not even be parsed, insert a non-standard <!-- eslint-skip --> comment before the block, and this plugin will hide the following block from ESLint. Neither rule nor syntax errors will be reported.

There are comments in this JSON, so we use `js` syntax for better
highlighting. Skip the block to prevent warnings about invalid syntax.

<!-- eslint-skip -->

```js
{
    // This code block is hidden from ESLint.
    "hello": "world"
}
```

```js
console.log("This code block is linted normally.");
```

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-plugin-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-plugin-markdown configuration comments and skip directives won't work in this context.

Contributing

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

This project follows the ESLint contribution guidelines.