From 1ae2b0bf6d80a762155f02ef717b975fee3f4598 Mon Sep 17 00:00:00 2001 From: michael faith Date: Sun, 12 Oct 2025 14:54:51 -0500 Subject: [PATCH 1/6] docs: add migration docs This change adds a new migration.md file where details about major migrations can be documented. The first section is details about migrating from the previous implementation `eslint-plugin-markdown`. --- docs/migration.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 docs/migration.md diff --git a/docs/migration.md b/docs/migration.md new file mode 100644 index 00000000..d7f9036a --- /dev/null +++ b/docs/migration.md @@ -0,0 +1,132 @@ +# Migration + +## From `eslint-plugin-markdown` + +Starting with v6, `@eslint/markdown` officially replaced `eslint-plugin-markdown`. +You can take the following steps to migrate from the old package. + +> [!NOTE] +> `@eslint/markdown` requires that you're on at least ESLint v9. + +### Update dependencies + +- `pnpm remove eslint-plugin-markdown` +- `pnpm add -D @eslint/markdown` + +### Update `eslint.config.js/ts` + +Make the following updates to your config, based on how you're currently using `eslint-plugin-markdown`. + +#### Configs + +```diff +// eslint.config.js +import { defineConfig } from "eslint/config"; +- import markdown from "eslint-plugin-markdown"; ++ import markdown from "@eslint/markdown"; + +export default defineConfig([ +- ...markdown.configs.recommended, ++ markdown.configs.recommended, + + // your other configs +]); + +``` + +If you were previously applying rules from other languages to code blocks within your markdown files, you can use this plugin's `processor` config to still allow for that. + +```js +// eslint.config.js +import { defineConfig } from "eslint/config"; +import markdown from "@eslint/markdown"; + +export default defineConfig([ + markdown.configs.recommended, + markdown.configs.processor, + + // your other configs +]); +``` + +[!IMPORTANT] +> Because this plugin uses a new language to power its linting, you may need to update the other configs you're using so that you limit those to only apply to `js / ts` files. +> Otherwise, those rules will be applied to markdown files now, too, which can lead to unexpected failures. + +```js +// eslint.config.js +import { defineConfig } from "eslint/config"; +import js from "@eslint/js"; +import markdown from "@eslint/markdown"; + +export default defineConfig([ + { + name: "your-project/recommended-rules", + files: ["**/*.js"], + plugins: { + js, + }, + extends: ["js/recommended"], + }, + markdown.configs.recommended, +]); +``` + +#### Rules Only + +`@eslint/markdown` is significantly different in its architecture than `eslint-plugin-markdown`, and uses the language feature of `ESLint`, rather than using a processor. +As a result, if you want to configure rules directly (instead of using the recommended config), you'll have to set up the language instead of the processor. + +```diff +// eslint.config.js +import { defineConfig } from "eslint/config"; +- import markdown from "eslint-plugin-markdown"; ++ import markdown from "@eslint/markdown"; + +export default defineConfig([ + { + files: ["**/*.md"], + plugins: { + markdown, + }, +- processor: "markdown/markdown" ++ language: "markdown/commonmark", + rules: { + "markdown/no-html": "error", + }, + }, +]); + +``` + +[!IMPORTANT] +> Because this plugin uses a new language to power its linting, you may need to update the other configs you're using so that you limit those to only apply to `js / ts` files. +> Otherwise, those rules will be applied to markdown files now, too, which can lead to unexpected failures. + +```js +// eslint.config.js +import { defineConfig } from "eslint/config"; +import js from "@eslint/js"; +import markdown from "@eslint/markdown"; + +export default defineConfig([ + { + name: "your-project/recommended-rules", + files: ["**/*.js"], + plugins: { + js, + }, + extends: ["js/recommended"], + }, + { + files: ["**/*.md"], + plugins: { + markdown, + }, + language: "markdown/commonmark", + rules: { + "markdown/no-html": "error", + }, + }, +]); +``` From 3f574bb52f473254584a68d0f3214e42a7fe5512 Mon Sep 17 00:00:00 2001 From: michael faith Date: Tue, 14 Oct 2025 12:45:03 -0500 Subject: [PATCH 2/6] address lint errors --- docs/migration.md | 5 +++-- package.json | 3 +++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/migration.md b/docs/migration.md index d7f9036a..4afe5e0b 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -5,6 +5,7 @@ Starting with v6, `@eslint/markdown` officially replaced `eslint-plugin-markdown`. You can take the following steps to migrate from the old package. + > [!NOTE] > `@eslint/markdown` requires that you're on at least ESLint v9. @@ -48,7 +49,7 @@ export default defineConfig([ // your other configs ]); ``` - + [!IMPORTANT] > Because this plugin uses a new language to power its linting, you may need to update the other configs you're using so that you limit those to only apply to `js / ts` files. > Otherwise, those rules will be applied to markdown files now, too, which can lead to unexpected failures. @@ -98,7 +99,7 @@ export default defineConfig([ ]); ``` - + [!IMPORTANT] > Because this plugin uses a new language to power its linting, you may need to update the other configs you're using so that you limit those to only apply to `js / ts` files. > Otherwise, those rules will be applied to markdown files now, too, which can lead to unexpected failures. diff --git a/package.json b/package.json index 52d01489..5c8ea689 100644 --- a/package.json +++ b/package.json @@ -75,6 +75,8 @@ "devDependencies": { "@eslint/js": "^9.36.0", "@eslint/json": "^0.13.2", + "@types/mdast": "^4.0.4", + "@types/unist": "^3.0.3", "c8": "^10.1.3", "dedent": "^1.5.3", "eslint": "^9.36.0", @@ -84,6 +86,7 @@ "lint-staged": "^15.2.9", "mocha": "^11.6.0", "prettier": "^3.3.3", + "semver": "^7.7.3", "typescript": "^5.9.2", "yorkie": "^2.0.0" }, From 4c9541a0b26a2159b69b2a7785cc260c38babc52 Mon Sep 17 00:00:00 2001 From: michael faith Date: Wed, 15 Oct 2025 06:17:26 -0500 Subject: [PATCH 3/6] add additional package managers and fix important notices --- docs/migration.md | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/migration.md b/docs/migration.md index 4afe5e0b..ac1f87f9 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -7,12 +7,34 @@ You can take the following steps to migrate from the old package. > [!NOTE] -> `@eslint/markdown` requires that you're on at least ESLint v9. +> `@eslint/markdown` requires that you're on at least ESLint v9.15.0. ### Update dependencies -- `pnpm remove eslint-plugin-markdown` -- `pnpm add -D @eslint/markdown` +```sh +pnpm remove eslint-plugin-markdown +pnpm add -D @eslint/markdown + +# or + +npm remove eslint-plugin-markdown +npm add -D @eslint/markdown + +# or + +yarn remove eslint-plugin-markdown +yarn add -D @eslint/markdown + +# or + +bun remove eslint-plugin-markdown +bun add -D @eslint/markdown + +# or + +deno remove eslint-plugin-markdown +deno add jsr:@eslint/markdown +``` ### Update `eslint.config.js/ts` @@ -50,7 +72,7 @@ export default defineConfig([ ]); ``` -[!IMPORTANT] +> [!IMPORTANT] > Because this plugin uses a new language to power its linting, you may need to update the other configs you're using so that you limit those to only apply to `js / ts` files. > Otherwise, those rules will be applied to markdown files now, too, which can lead to unexpected failures. @@ -100,7 +122,7 @@ export default defineConfig([ ``` -[!IMPORTANT] +> [!IMPORTANT] > Because this plugin uses a new language to power its linting, you may need to update the other configs you're using so that you limit those to only apply to `js / ts` files. > Otherwise, those rules will be applied to markdown files now, too, which can lead to unexpected failures. From 517e57aac3957dbc80a4fb3cdfbd37848c99e5fe Mon Sep 17 00:00:00 2001 From: michael faith Date: Wed, 15 Oct 2025 06:24:07 -0500 Subject: [PATCH 4/6] update config section --- docs/migration.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/docs/migration.md b/docs/migration.md index ac1f87f9..96627d32 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -57,20 +57,6 @@ export default defineConfig([ ``` -If you were previously applying rules from other languages to code blocks within your markdown files, you can use this plugin's `processor` config to still allow for that. - -```js -// eslint.config.js -import { defineConfig } from "eslint/config"; -import markdown from "@eslint/markdown"; - -export default defineConfig([ - markdown.configs.recommended, - markdown.configs.processor, - - // your other configs -]); -``` > [!IMPORTANT] > Because this plugin uses a new language to power its linting, you may need to update the other configs you're using so that you limit those to only apply to `js / ts` files. @@ -95,6 +81,25 @@ export default defineConfig([ ]); ``` +If you were previously applying rules from other languages to code blocks within your markdown files, you can use this plugin's `processor` config to still allow for that. + +```js +// eslint.config.js +import { defineConfig } from "eslint/config"; +import markdown from "@eslint/markdown"; + +export default defineConfig([ + markdown.configs.processor, + + // your other configs +]); +``` + + +> [!WARNING] +> It is not currently possible to use both the language-based `recommended` config and the processor-based `processor` config, due to a limitation in ESLint core. +> We hope at some point in the future the core will have a solution for this. + #### Rules Only `@eslint/markdown` is significantly different in its architecture than `eslint-plugin-markdown`, and uses the language feature of `ESLint`, rather than using a processor. @@ -148,7 +153,7 @@ export default defineConfig([ }, language: "markdown/commonmark", rules: { - "markdown/no-html": "error", + "markdown/no-html": "error", }, }, ]); From cc39e9edd69806c2bf19995cfc2b6073aa66b82e Mon Sep 17 00:00:00 2001 From: michael faith Date: Wed, 15 Oct 2025 06:28:20 -0500 Subject: [PATCH 5/6] add link to README --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 1be0db3a..e7d1ed69 100644 --- a/README.md +++ b/README.md @@ -220,6 +220,10 @@ export default defineConfig([ | ------------------------------------------- | ----------------------------------------------------------------------------------- | | [`markdown`](./docs/processors/markdown.md) | Extract fenced code blocks from the Markdown code so they can be linted separately. | +## Migration from `eslint-plugin-markdown` + +See [Migration](./docs/migration.md#from-eslint-plugin-markdown). + ## Editor Integrations ### VSCode From 1ebbe17109de598e46d2299e3b9b52d273aef5fe Mon Sep 17 00:00:00 2001 From: michael faith Date: Wed, 15 Oct 2025 18:01:14 -0500 Subject: [PATCH 6/6] address feedback --- README.md | 9 ++++++-- docs/migration.md | 54 +++++++++++++++++++++++------------------------ 2 files changed, 33 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index e7d1ed69..fff0ebd2 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,13 @@ import { defineConfig } from "eslint/config"; import markdown from "@eslint/markdown"; export default defineConfig([ - markdown.configs.recommended, - + { + files: ["**/*.md"], + plugins: { + markdown, + }, + extends: ["markdown/recommended"], + }, // your other configs here ]); ``` diff --git a/docs/migration.md b/docs/migration.md index 96627d32..4a602654 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -11,30 +11,8 @@ You can take the following steps to migrate from the old package. ### Update dependencies -```sh -pnpm remove eslint-plugin-markdown -pnpm add -D @eslint/markdown - -# or - -npm remove eslint-plugin-markdown -npm add -D @eslint/markdown - -# or - -yarn remove eslint-plugin-markdown -yarn add -D @eslint/markdown - -# or - -bun remove eslint-plugin-markdown -bun add -D @eslint/markdown - -# or - -deno remove eslint-plugin-markdown -deno add jsr:@eslint/markdown -``` +- `npm remove eslint-plugin-markdown` +- `npm add -D @eslint/markdown` ### Update `eslint.config.js/ts` @@ -50,7 +28,14 @@ import { defineConfig } from "eslint/config"; export default defineConfig([ - ...markdown.configs.recommended, -+ markdown.configs.recommended, ++ { ++ name: "your-project/markdown-rules", ++ files: ["**/*.md"], ++ plugins: { ++ markdown ++ }, ++ extends: ["markdown/recommended"] + }, // your other configs ]); @@ -77,7 +62,14 @@ export default defineConfig([ }, extends: ["js/recommended"], }, - markdown.configs.recommended, + { + name: "your-project/markdown-rules", + files: ["**/*.md"], + plugins: { + markdown + }, + extends: ["markdown/recommended"] + }, ]); ``` @@ -89,8 +81,14 @@ import { defineConfig } from "eslint/config"; import markdown from "@eslint/markdown"; export default defineConfig([ - markdown.configs.processor, - + { + name: "your-project/markdown-processor", + files: ["**/*.md"], + plugins: { + markdown + }, + extends: ["markdown/processor"] + }, // your other configs ]); ```