https://github.com/eslint/markdown
Lint JavaScript code blocks in Markdown documents
https://github.com/eslint/markdown
development ecmascript eslint javascript linter markdown static-code-analysis
Last synced: 25 days ago
JSON representation
Lint JavaScript code blocks in Markdown documents
- Host: GitHub
- URL: https://github.com/eslint/markdown
- Owner: eslint
- License: mit
- Created: 2015-07-01T18:00:13.000Z (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2025-05-12T12:12:49.000Z (26 days ago)
- Last Synced: 2025-05-12T12:44:23.400Z (26 days ago)
- Topics: development, ecmascript, eslint, javascript, linter, markdown, static-code-analysis
- Language: JavaScript
- Homepage:
- Size: 504 KB
- Stars: 448
- Watchers: 21
- Forks: 69
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-remark - eslint-plugin-markdown - Lint JavaScript in markdown. (Built on remark)
README
# 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 JS, JSX, TypeScript, and more inside Markdown.
## Usage
### Installing
Install the plugin alongside ESLint v9 or greater:
```sh
npm install --save-dev eslint @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
| **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-duplicate-headings`](./docs/rules/no-duplicate-headings.md) | Disallow duplicate headings in the same document | no |
| [`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-label-refs`](./docs/rules/no-missing-label-refs.md) | Disallow missing label references | yes |
**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
Hello world!
Goodbye world!
[Object]
```
### 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. |
```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"` to enable TOML 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/).
## 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).
Diamond Sponsors
Platinum Sponsors
Gold Sponsors
Silver Sponsors
Bronze Sponsors
Technology Sponsors
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.
