In ESLint 10, how do you lint JavaScript code blocks inside Markdown files with a processor, and how does that differ from a `language` such as `json/jsonc`?
answer
- extract, lint, map back
- processor: namespace/processor-name
- code blocks become child files
- a pattern like **/*.md/*.js
- a language parses the whole file
basics
~20 sA processor such as markdown/markdown extracts each code block as a virtual child file that JavaScript rules lint; a language such as json/jsonc, available since ESLint 9.7.0, makes ESLint parse the whole file as that language.
solid answer
~40 sA processor is a plugin's `preprocess`/`postprocess` pair. With `@eslint/markdown` registered as `markdown`, an object with `files: ["**/*.md"]` and `processor: "markdown/markdown"` makes ESLint pull each code block out as a named child file such as `runbook.md/0.js`, lint it with whatever config matches that name, and map the messages back to the Markdown lines. Extra settings for those blocks target `**/*.md/*.js`, and global ignores apply to them too. A language, added in ESLint 9.7.0, replaces the parser and source model: `language: "json/jsonc"` from `@eslint/json` makes ESLint read the file as JSONC, with that language's own `languageOptions` and rules written for it. Rule of thumb: code embedded in another file needs a processor; checking the file's own syntax needs a language.
code
javascript · 21 lines// @crewdeck/eslint-config - docs.js
import markdown from "@eslint/markdown";
import json from "@eslint/json";
import { defineConfig } from "eslint/config";
export default defineConfig([
{
files: ["**/*.md"],
plugins: { markdown },
processor: "markdown/markdown", // each code block becomes a child file
},
{
files: ["**/*.md/*.js"], // only the extracted JavaScript blocks
rules: { "no-undef": "off" }, // runbook snippets use undeclared names
},
{
files: ["**/*.json"],
plugins: { json },
language: "json/jsonc", // the whole file is parsed as JSONC
},
]);go deeper
Recall that processor pulls code out of another file for normal linting, while language switches what kind of file ESLint parses.
Explain the child-file naming such as runbook.md/0.js, the **/.md/.js pattern, and that language changes the parser and languageOptions.
Keep JavaScript presets scoped with files once non-JavaScript patterns appear, and know which code blocks are skipped or globally ignored.
Decide whether documentation snippets and data files belong in the lint gate at all, and ship that choice as a separate entry of the shared config.
## Two ways ESLint reaches non-JavaScript files Out of the box ESLint lints `**/*.js`, `**/*.cjs` and `**/*.mjs` as JavaScript. Plugins offer two different ways past that: - A **processor** extracts JavaScript (or other code) from inside another file and hands the pieces to the normal linting pipeline. - A **language**, supported since ESLint 9.7.0, teaches ESLint to parse and traverse a different language entirely, so rules can check JSON, Markdown and others as themselves. Both come from plugins, both are usually referenced as `namespace/name` strings, and a string reference needs the plugin registered under that namespace in `plugins`. ## Processors: extract, lint, map back A processor is an object with `preprocess(text, filename)` and `postprocess(messages, filename)`. With `processor: "markdown/markdown"` set for `**/*.md`, linting `docs/runbook.md` works like this: 1. `preprocess` receives the Markdown text and returns an array of **code blocks**, each with its own `text` and a `filename` such as `0.js` or `1.jsx`. 2. ESLint treats each block as a **child file** of the original: `docs/runbook.md/0.js`. 3. Each child file is linted with the config objects that match **its** path, so your JavaScript rules apply. 4. `postprocess` receives the messages for every block and maps their locations back to lines in the Markdown file. You see problems reported against `runbook.md`, at the right line, even though rules only ever saw JavaScript. ## Configuring the code blocks - Target the blocks with patterns on the child path: `files: ["**/*.md/*.js"]` matches JavaScript blocks inside any Markdown file. - Runbook snippets often reference names they never declare, so a block-only object is the place to relax a rule like `no-undef`. - ESLint lints a named block only if it is a JavaScript file or matches some object's `files`; a `0.ts` block with no matching object is skipped. - Global ignores apply to code blocks too, so `**/test.md/*.jsx` in a global `ignores` object skips those blocks. - The processor itself only extracts; whatever lints the blocks is your ordinary config. ## Languages: the `language` key A configuration object's `language` key names a language in `"pluginName/languageName"` form. Its default is `"js/js"`, ESLint's built-in JavaScript. Setting `language: "json/jsonc"` with `@eslint/json` registered as `json` means: - the file is parsed by that language's parser into its own tree; - `languageOptions` now holds that language's options, not JavaScript's; - the rules you configure for those files run against that tree, so they must be written for that language, and a rule whose `meta.languages` lists only other languages makes ESLint throw. Markdown itself can be linted the same way through a Markdown language, such as the `"markdown/commonmark"` that ESLint's docs use as an example, which checks the Markdown structure rather than the code inside it. ## Keeping JavaScript presets off other files A config object without `files` applies to every file any other object matches. Once you add `**/*.json` or `**/*.md`, an unscoped JavaScript preset reaches those files too. Scope JavaScript presets with `files` such as `["**/*.{js,jsx}"]`; the child paths of extracted blocks still match it. ## A runbook walk-through Suppose `docs/rotations.md` contains three fenced blocks: a JavaScript snippet, a JSX snippet and a shell session. With the processor attached to `**/*.md`: 1. The JavaScript block becomes `docs/rotations.md/0.js` and matches every object whose `files` cover `**/*.js` or `**/*.md/*.js`. 2. The JSX block becomes `docs/rotations.md/1.jsx` and is linted only if some object's `files` match `.jsx` names. 3. The shell block either is not extracted or is skipped, because it is neither JavaScript nor matched by any `files` entry. 4. Messages from blocks 0 and 1 are mapped back and reported against `docs/rotations.md` at the original line numbers. The Markdown file's own structure, such as heading levels, is never checked by this setup; that would need a Markdown language and rules written for it. ## Processor or language | Question | Processor | Language | |---|---|---| | What gets linted | Code embedded in the file | The file's own syntax | | Config key | `processor: "markdown/markdown"` | `language: "json/jsonc"` | | Rules that run | Your JavaScript rules, on each block | Rules written for that language | | Extra config | Objects matching `**/*.md/*.js` | `languageOptions` of that language | | Available since | The eslintrc era, kept in flat config | ESLint 9.7.0 |
- After adding a `**/*.json` object, JavaScript rules start failing on JSON files. Why?Config objects without `files` apply to every file any object matches, so adding a JSON pattern pulls JSON files into unscoped JavaScript presets. Give the JavaScript presets explicit `files`, for example `["**/*.{js,jsx}"]`, so only JavaScript and extracted JavaScript blocks reach them.
- Can extracted Markdown blocks get JSX parsing?Yes. Blocks named `0.jsx` are child files ending in `.jsx`, so an object with `files: ["**/*.jsx"]` that enables JSX in `languageOptions.parserOptions.ecmaFeatures` applies to them as well as to ordinary `.jsx` files.
- A Markdown processor lints the Markdown itself, its headings and links.
- Processor and language are interchangeable keys for the same feature.
- Extracted code blocks are configured only through the Markdown object.
- Global ignores never apply to code blocks extracted by a processor.
- JavaScript presets without files never reach Markdown or JSON files.
Assumes ESLint 10; the language key and language plugins arrived in ESLint 9.7.0, while processors predate flat config and are referenced as namespace/processor-name strings in flat config.