docs: add migration docs

docs/migration.md

@@ -0,0 +1,133 @@
+# 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.
+
+<!-- eslint-disable-next-line markdown/no-missing-label-refs -- This should be fixed in https://github.com/eslint/markdown/issues/294 -->
+> [!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
+]);
+```
+<!-- eslint-disable-next-line markdown/no-missing-label-refs -- This should be fixed in https://github.com/eslint/markdown/issues/294 -->
+[!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",
+    },
+  },
+]);
+
+```
+<!-- eslint-disable-next-line markdown/no-missing-label-refs -- This should be fixed in https://github.com/eslint/markdown/issues/294 -->
+[!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",
+    },
+  },
+]);
+```

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"
   },