@eslint/markdown
Version:
The official ESLint language plugin for Markdown
266 lines (205 loc) • 12.7 kB
Markdown
# ESLint Markdown Language Plugin
[](https://www.npmjs.com/package/@eslint/markdown)
[](https://www.npmjs.com/package/@eslint/markdown)
[](https://github.com/eslint/markdown/actions)
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 or greater.
For Node.js and compatible runtimes:
```sh
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:
```sh
deno add jsr:@eslint/markdown
```
### Configurations
| **Configuration Name** | **Description** |
|---------------|-----------------|
| `recommended` | Lints all `.md` files with the recommended rules and assumes [CommonMark](https://commonmark.org/) 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:
```js
// 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`:
```js
// 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`](./docs/rules/fenced-code-language.md) | Require languages for fenced code blocks | yes |
| [`heading-increment`](./docs/rules/heading-increment.md) | Enforce heading levels increment by one | yes |
| [`no-bare-urls`](./docs/rules/no-bare-urls.md) | Disallow bare URLs | no |
| [`no-duplicate-definitions`](./docs/rules/no-duplicate-definitions.md) | Disallow duplicate definitions | yes |
| [`no-duplicate-headings`](./docs/rules/no-duplicate-headings.md) | Disallow duplicate headings in the same document | no |
| [`no-empty-definitions`](./docs/rules/no-empty-definitions.md) | Disallow empty definitions | yes |
| [`no-empty-images`](./docs/rules/no-empty-images.md) | Disallow empty images | yes |
| [`no-empty-links`](./docs/rules/no-empty-links.md) | Disallow empty links | yes |
| [`no-html`](./docs/rules/no-html.md) | Disallow HTML tags | no |
| [`no-invalid-label-refs`](./docs/rules/no-invalid-label-refs.md) | Disallow invalid label references | yes |
| [`no-missing-atx-heading-space`](./docs/rules/no-missing-atx-heading-space.md) | Disallow headings without a space after the hash characters | yes |
| [`no-missing-label-refs`](./docs/rules/no-missing-label-refs.md) | Disallow missing label references | yes |
| [`no-missing-link-fragments`](./docs/rules/no-missing-link-fragments.md) | Disallow link fragments that do not reference valid headings | yes |
| [`no-multiple-h1`](./docs/rules/no-multiple-h1.md) | Disallow multiple H1 headings in the same document | yes |
| [`no-reversed-media-syntax`](./docs/rules/no-reversed-media-syntax.md) | Disallow reversed link and image syntax | yes |
| [`no-unused-definitions`](./docs/rules/no-unused-definitions.md) | Disallow unused definitions | yes |
| [`require-alt-text`](./docs/rules/require-alt-text.md) | Require alternative text for images | yes |
| [`table-column-count`](./docs/rules/table-column-count.md) | 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](https://prettier.io) 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:
```js
// 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:
```markdown
<!-- 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](https://commonmark.org) Markdown format |
| `gfm` | Parse using [GitHub-Flavored Markdown](https://github.github.com/gfm/) format |
In order to individually configure a language in your `eslint.config.js` file, import `@eslint/markdown` and configure a `language`:
```js
// 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](https://jekyllrb.com/docs/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`](https://github.com/micromark/micromark-extension-frontmatter) and [`mdast-util-frontmatter`](https://github.com/syntax-tree/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. |
| `"json"` | Enables JSON front matter parsing in Markdown files. |
```js
// 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"` or `"json"` to enable TOML or JSON front matter parsing.
},
rules: {
"markdown/no-html": "error"
}
}
]);
```
### Processors
| **Processor Name** | **Description** |
|---------------|-----------------|
| [`markdown`](./docs/processors/markdown.md) | Extract fenced code blocks from the Markdown code so they can be linted separately. |
## Editor Integrations
### VSCode
[`vscode-eslint`](https://github.com/microsoft/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`:
````md
```js filename="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"`.
## Contributing
```sh
$ git clone https://github.com/eslint/markdown.git
$ cd markdown
$ npm install
$ npm test
```
This project follows the [ESLint contribution guidelines](https://eslint.org/docs/latest/contribute/).
<!-- NOTE: This section is autogenerated. Do not manually edit.-->
<!--sponsorsstart-->
## Sponsors
The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. [Become a Sponsor](https://eslint.org/donate)
to get your logo on our READMEs and [website](https://eslint.org/sponsors).
<h3>Diamond Sponsors</h3>
<p><a href="https://www.ag-grid.com/"><img src="https://images.opencollective.com/ag-grid/bec0580/logo.png" alt="AG Grid" height="128"></a></p><h3>Platinum Sponsors</h3>
<p><a href="https://automattic.com"><img src="https://images.opencollective.com/automattic/d0ef3e1/logo.png" alt="Automattic" height="128"></a> <a href="https://www.airbnb.com/"><img src="https://images.opencollective.com/airbnb/d327d66/logo.png" alt="Airbnb" height="128"></a></p><h3>Gold Sponsors</h3>
<p><a href="https://qlty.sh/"><img src="https://images.opencollective.com/qltysh/33d157d/logo.png" alt="Qlty Software" height="96"></a> <a href="https://trunk.io/"><img src="https://images.opencollective.com/trunkio/fb92d60/avatar.png" alt="trunk.io" height="96"></a> <a href="https://shopify.engineering/"><img src="https://avatars.githubusercontent.com/u/8085" alt="Shopify" height="96"></a></p><h3>Silver Sponsors</h3>
<p><a href="https://vite.dev/"><img src="https://images.opencollective.com/vite/e6d15e1/logo.png" alt="Vite" height="64"></a> <a href="https://liftoff.io/"><img src="https://images.opencollective.com/liftoff/5c4fa84/logo.png" alt="Liftoff" height="64"></a> <a href="https://americanexpress.io"><img src="https://avatars.githubusercontent.com/u/3853301" alt="American Express" height="64"></a> <a href="https://stackblitz.com"><img src="https://avatars.githubusercontent.com/u/28635252" alt="StackBlitz" height="64"></a></p><h3>Bronze Sponsors</h3>
<p><a href="https://cybozu.co.jp/"><img src="https://images.opencollective.com/cybozu/933e46d/logo.png" alt="Cybozu" height="32"></a> <a href="https://sentry.io"><img src="https://github.com/getsentry.png" alt="Sentry" height="32"></a> <a href="https://www.crosswordsolver.org/anagram-solver/"><img src="https://images.opencollective.com/anagram-solver/2666271/logo.png" alt="Anagram Solver" height="32"></a> <a href="https://icons8.com/"><img src="https://images.opencollective.com/icons8/7fa1641/logo.png" alt="Icons8" height="32"></a> <a href="https://discord.com"><img src="https://images.opencollective.com/discordapp/f9645d9/logo.png" alt="Discord" height="32"></a> <a href="https://www.gitbook.com"><img src="https://avatars.githubusercontent.com/u/7111340" alt="GitBook" height="32"></a> <a href="https://nx.dev"><img src="https://avatars.githubusercontent.com/u/23692104" alt="Nx" height="32"></a> <a href="https://opensource.mercedes-benz.com/"><img src="https://avatars.githubusercontent.com/u/34240465" alt="Mercedes-Benz Group" height="32"></a> <a href="https://herocoders.com"><img src="https://avatars.githubusercontent.com/u/37549774" alt="HeroCoders" height="32"></a> <a href="https://www.lambdatest.com"><img src="https://avatars.githubusercontent.com/u/171592363" alt="LambdaTest" height="32"></a></p>
<h3>Technology Sponsors</h3>
Technology sponsors allow us to use their products and services for free as part of a contribution to the open source ecosystem and our work.
<p><a href="https://netlify.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/netlify-icon.svg" alt="Netlify" height="32"></a> <a href="https://algolia.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/algolia-icon.svg" alt="Algolia" height="32"></a> <a href="https://1password.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/1password-icon.svg" alt="1Password" height="32"></a></p>
<!--sponsorsend-->