To lint Markdown with ESLint, configure the official @eslint/markdown plugin in ESLint’s flat configuration. Use its recommended config to check Markdown content, or its processor config to lint code inside fenced blocks. Those are separate jobs: to check both prose and embedded code, create two configurations and run ESLint twice.
If you’re asking “How do I lint Markdown with ESLint?” or “How do I lint JavaScript code blocks in Markdown with ESLint?”, the distinction between these two configurations is the key to getting the results you expect.
As an Amazon Associate I earn from qualifying purchases.
Install the official Markdown plugin
The current package is @eslint/markdown, the official ESLint Markdown Language Plugin. Its README specifies ESLint v9.15.0 or greater. Install it and ESLint with your project’s package manager:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →npm install --save-dev eslint @eslint/markdownESLint 9 uses flat config by default. Put the configuration in eslint.config.js and use flat-config syntax rather than older .eslintrc examples.
#1 Best Overall
Choose what you want ESLint to check
| Goal | Configuration | What the run checks |
|---|---|---|
| Markdown structure and conventions | markdown/recommended |
Markdown documents, including rules such as heading increments and required image alt text |
| Code inside fenced blocks | markdown/processor |
Extracted code blocks that match configured file patterns |
| Both Markdown and fenced code | Both configurations, in separate configs | Run ESLint once for Markdown content and once for extracted code |
These configurations are not interchangeable. A processor-based run lints extracted code blocks, not the surrounding Markdown content.
Lint Markdown content with the recommended config
For Markdown-specific checks, import the plugin and spread its recommended configuration into your flat config:
Rank #2
import markdown from "@eslint/markdown";
export default [
markdown.configs.recommended,
];The recommended config applies Markdown language support and recommended rules to .md files. It assumes CommonMark. Examples of rules in the recommended set include fenced-code-language, heading-increment, no-reversed-media-syntax, no-space-in-emphasis, no-unused-definitions, require-alt-text, and table-column-count. The rule fenced-code-meta is available but is not recommended by default.
Use GitHub Flavored Markdown when needed
If your documents use GitHub Flavored Markdown (GFM), configure that language explicitly instead of relying on the recommended config’s CommonMark assumption. The plugin documents support for both CommonMark and GFM; use the language option appropriate to the syntax your project uses.
Enable front matter or math only when your files need it
Parsing for YAML, TOML, or JSON front matter and math syntax is optional and disabled by default. Enable the relevant language options when your Markdown files actually contain those constructs; otherwise, the default configuration avoids treating them as supported extensions.
Lint code inside fenced Markdown blocks
To lint embedded code, configure the plugin’s processor for Markdown files. The processor extracts tagged fenced blocks as virtual files, allowing ESLint to apply rules configured for the corresponding file types:
Rank #4
import markdown from "@eslint/markdown";
export default [
{
files: ["**/*.md"],
plugins: { markdown },
processor: "markdown/processor",
},
{
files: ["**/*.js"],
rules: {
// Add the JavaScript rules used by your project.
},
},
];Use language tags that correspond to extensions included in your configuration’s file patterns. Untagged fenced blocks are ignored. The processor maps javascript and ecmascript to .js, typescript to .ts, and markdown to .md virtual filenames. For example, a javascript block can be linted when your ESLint config includes a matching JavaScript file pattern.
Run separate checks for Markdown and embedded code
The processor limitation matters if you want one command to report on both prose and code: the processor-based run only lints extracted blocks. Follow the plugin’s documented two-configuration, two-run arrangement instead.
- For Markdown content: use a config containing
markdown.configs.recommended, without the processor, then run ESLint on your Markdown files:npx eslint "**/*.md". - For fenced code: use a separate config with
markdown/processorand the code-language rules and file patterns your project needs, then run ESLint on the Markdown files again:npx eslint --config eslint.code.config.js "**/*.md".
Name and locate the two config files to suit your project. The important part is that the processor run and the Markdown-content run use separate configurations.
Formatting is a separate concern
The plugin provides lint rules, not formatting rules. Its maintainers recommend using a source-code formatter such as Prettier for formatting. Use the linter to report Markdown conventions and code issues; add a formatter separately if you need automatic formatting.
Updating older Markdown lint configurations
Older guides may use eslint-plugin-markdown and eslintrc-style configuration. The current official package is @eslint/markdown, and current ESLint setup examples use flat config. If you are migrating an existing project, follow the migration guidance in the plugin README rather than copying legacy configuration into a new setup.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
