Skip to main content

Built and signed on GitHub Actions

Official ESLint Markdown language plugin

This package works with Cloudflare Workers, Node.js, Deno, Bun, Browsers
This package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
This package works with Bun
This package works with Browsers
JSR Score
47%
Published
a week ago (6.2.0)

ESLint Markdown Language Plugin

npm Version Downloads Build Status

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

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

Built and signed on
GitHub Actions
View transparency log

Add Package

deno add jsr:@eslint/markdown

Import symbol

import * as mod from "@eslint/markdown";

---- OR ----

Import directly with a jsr specifier

import * as mod from "jsr:@eslint/markdown";

Add Package

npx jsr add @eslint/markdown

Import symbol

import * as mod from "@eslint/markdown";

Add Package

yarn dlx jsr add @eslint/markdown

Import symbol

import * as mod from "@eslint/markdown";

Add Package

pnpm dlx jsr add @eslint/markdown

Import symbol

import * as mod from "@eslint/markdown";

Add Package

bunx jsr add @eslint/markdown

Import symbol

import * as mod from "@eslint/markdown";