ESLint Markdown Language Plugin

Lint Markdown with ESLint, as well JS, JSX, TypeScript, and more inside Markdown.

<img src="screenshot.png" height="142" width="432" alt="A JS code snippet in a Markdown editor has red squiggly underlines. A tooltip explains the problem." />

Usage

Installing

Install the plugin alongside ESLint v9.15.0 or greater.

For Node.js and compatible runtimes:

npm install @eslint/markdown -D
# or
yarn add @eslint/markdown -D
# or
pnpm install @eslint/markdown -D
# or
bun add @eslint/markdown -D

For Deno:

deno add jsr:@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 Markdown parsing and linting:

// eslint.config.js
import { defineConfig } from "eslint/config";
import markdown from "@eslint/markdown";

export default defineConfig([
	{
		files: ["**/*.md"],
		plugins: {
			markdown,
		},
		extends: ["markdown/recommended"],
	},
	// your other configs here
]);

You can also modify the recommended config by using extends:

// eslint.config.js
import { defineConfig } from "eslint/config";
import markdown from "@eslint/markdown";

export default defineConfig([
	{
		plugins: {
			markdown,
		},
		extends: ["markdown/recommended"],
		rules: {
			"markdown/no-html": "error",
		},
	},

	// your other configs here
]);

Rules

<!-- NOTE: The following table is autogenerated. Do not manually edit. --> <!-- Rule Table Start -->

| Rule Name | Description | Recommended | | :----------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :-------------: | | fenced-code-language | Require languages for fenced code blocks | yes | | fenced-code-meta | Require or disallow metadata for fenced code blocks | no | | heading-increment | Enforce heading levels increment by one | yes | | no-bare-urls | Disallow bare URLs | no | | no-duplicate-definitions | Disallow duplicate definitions | yes | | no-duplicate-headings | Disallow duplicate headings in the same document | no | | no-empty-definitions | Disallow empty definitions | yes | | no-empty-images | Disallow empty images | yes | | no-empty-links | Disallow empty links | yes | | no-html | Disallow HTML tags | no | | no-invalid-label-refs | Disallow invalid label references | yes | | no-missing-atx-heading-space | Disallow headings without a space after the hash characters | yes | | no-missing-label-refs | Disallow missing label references | yes | | no-missing-link-fragments | Disallow link fragments that do not reference valid headings | yes | | no-multiple-h1 | Disallow multiple H1 headings in the same document | yes | | no-reference-like-urls | Disallow URLs that match defined reference identifiers | yes | | no-reversed-media-syntax | Disallow reversed link and image syntax | yes | | no-space-in-emphasis | Disallow spaces around emphasis markers | yes | | no-unused-definitions | Disallow unused definitions | yes | | require-alt-text | Require alternative text for images | yes | | table-column-count | Disallow data rows in a GitHub Flavored Markdown table from having more cells than the header row | yes |

<!-- Rule Table End -->

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 { defineConfig } from "eslint/config";
import markdown from "@eslint/markdown";

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

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

<!-- prettier-ignore-start -->

<!-- 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 -->

<!-- prettier-ignore-end -->

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 { defineConfig } from "eslint/config";
import markdown from "@eslint/markdown";

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

Language Options

Enabling Front Matter in both commonmark and gfm

By default, Markdown parsers do not support front matter. To enable front matter in both commonmark and gfm, you can use the frontmatter option in languageOptions.

@eslint/markdown internally uses micromark-extension-frontmatter and mdast-util-frontmatter to parse front matter.

| Option Value | Description | | ---------------- | ---------------------------------------------------------- | | false | Disables front matter parsing in Markdown files. (Default) | | "yaml" | Enables YAML front matter parsing in Markdown files. | | "toml" | Enables TOML front matter parsing in