skip to content

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`?

level: seniorimportance: nice to knowfreq 6%

answer

  1. extract, lint, map back
  2. processor: namespace/processor-name
  3. code blocks become child files
  4. a pattern like **/*.md/*.js
  5. a language parses the whole file

basics

~20 s

A 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 s

A 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
javascript
// @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

for a junior

Recall that processor pulls code out of another file for normal linting, while language switches what kind of file ESLint parses.

for a middle

Explain the child-file naming such as runbook.md/0.js, the **/.md/.js pattern, and that language changes the parser and languageOptions.

for a senior

Keep JavaScript presets scoped with files once non-JavaScript patterns appear, and know which code blocks are skipped or globally ignored.

for a principal

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.