GitHub - eslint/markdown: Lint JavaScript code blocks in Markdown documents (original) (raw)

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 Markdown parsing and linting:

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

export default defineConfig([ markdown.configs.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

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-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-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 { 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:

Hello world!

Goodbye world!

[Object]

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 Markdown files.

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

export default defineConfig([ { files: ["**/*.md"], plugins: { markdown }, language: "markdown/gfm", languageOptions: { frontmatter: "yaml", // Or pass "toml" to enable TOML front matter parsing. }, 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.

File Name Details

This processor will use file names from blocks if a filename meta is present.

For example, the following block will result in a parsed file name of src/index.js:

export const value = "Hello, world!";

This can be useful for user configurations that include linting overrides for specific file paths. In this example, you could then target the specific code block in your configuration using "file-name.md/*src/index.js".