diff --git a/README.md b/README.md index 1be0db3a..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 ]); ``` @@ -220,6 +225,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 diff --git a/docs/migration.md b/docs/migration.md new file mode 100644 index 00000000..4a602654 --- /dev/null +++ b/docs/migration.md @@ -0,0 +1,158 @@ +# 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.15.0. + +### Update dependencies + +- `npm remove eslint-plugin-markdown` +- `npm 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, ++ { ++ name: "your-project/markdown-rules", ++ files: ["**/*.md"], ++ plugins: { ++ markdown ++ }, ++ extends: ["markdown/recommended"] + }, + + // 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"], + }, + { + name: "your-project/markdown-rules", + files: ["**/*.md"], + plugins: { + markdown + }, + extends: ["markdown/recommended"] + }, +]); +``` + +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([ + { + name: "your-project/markdown-processor", + files: ["**/*.md"], + plugins: { + markdown + }, + extends: ["markdown/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. +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", + }, + }, +]); +``` 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" },