feat(markdown)!: replace markdown-it-anchor with @mdit/plugin-anchor

Drop-in for our usage: identical defaults (min-level semantics,
tabindex, unique slug handling) and the same permalink/getTokensText
signatures, with proper ESM types - removing the type patch we carried
for markdown-it-anchor.

BREAKING CHANGE: `markdown.anchor` options are now typed by
`@mdit/plugin-anchor`. Common options (`level`, `slugify`, `permalink`,
`getTokensText`, `tabIndex`, etc.) are unchanged, but the deprecated
markdown-it-anchor permalink options (`permalinkSymbol`,
`renderPermalink`, ...) are no longer accepted. Permalink builders like
`headerLink` are named exports of `@mdit/plugin-anchor` instead of
properties of the plugin.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/en/guide/markdown.md

@@ -1043,15 +1043,15 @@ VitePress uses [markdown-it](https://github.com/markdown-it/markdown-it) as the
 
 ```js
 import { defineConfig } from 'vitepress'
-import markdownItAnchor from 'markdown-it-anchor'
+import { headerLink } from '@mdit/plugin-anchor'
 import markdownItFoo from 'markdown-it-foo'
 
 export default defineConfig({
   markdown: {
-    // options for markdown-it-anchor
-    // https://github.com/valeriangalliat/markdown-it-anchor#usage
+    // options for @mdit/plugin-anchor
+    // https://mdit-plugins.github.io/anchor.html
     anchor: {
-      permalink: markdownItAnchor.permalink.headerLink()
+      permalink: headerLink()
     },
 
     // options for @mdit-vue/plugin-toc

docs/es/guide/markdown.md

@@ -907,15 +907,15 @@ VitePress usa [markdown-it](https://github.com/markdown-it/markdown-it) como int
 
 ```js
 import { defineConfig } from 'vitepress'
-import markdownItAnchor from 'markdown-it-anchor'
+import { headerLink } from '@mdit/plugin-anchor'
 import markdownItFoo from 'markdown-it-foo'
 
 export default defineConfig({
   markdown: {
-    // opciones para markdown-it-anchor
-    // https://github.com/valeriangalliat/markdown-it-anchor#usage
+    // opciones para @mdit/plugin-anchor
+    // https://mdit-plugins.github.io/anchor.html
     anchor: {
-      permalink: markdownItAnchor.permalink.headerLink()
+      permalink: headerLink()
     },
 
     // opciones para @mdit-vue/plugin-toc

docs/fa/guide/markdown.md

@@ -899,15 +899,15 @@ export default {
 
 ```js
 import { defineConfig } from 'vitepress'
-import markdownItAnchor from 'markdown-it-anchor'
+import { headerLink } from '@mdit/plugin-anchor'
 import markdownItFoo from 'markdown-it-foo'
 
 export default defineConfig({
   markdown: {
-    // گزینه‌های markdown-it-anchor
-    // https://github.com/valeriangalliat/markdown-it-anchor#usage
+    // گزینه‌های @mdit/plugin-anchor
+    // https://mdit-plugins.github.io/anchor.html
     anchor: {
-      permalink: markdownItAnchor.permalink.headerLink()
+      permalink: headerLink()
     },
 
     // گزینه‌های @mdit-vue/plugin-toc

docs/ja/guide/markdown.md

@@ -1015,15 +1015,15 @@ VitePress は Markdown レンダラーとして [markdown-it](https://github.com
 
 ```js
 import { defineConfig } from 'vitepress'
-import markdownItAnchor from 'markdown-it-anchor'
+import { headerLink } from '@mdit/plugin-anchor'
 import markdownItFoo from 'markdown-it-foo'
 
 export default defineConfig({
   markdown: {
-    // markdown-it-anchor のオプション
-    // https://github.com/valeriangalliat/markdown-it-anchor#usage
+    // @mdit/plugin-anchor のオプション
+    // https://mdit-plugins.github.io/anchor.html
     anchor: {
-      permalink: markdownItAnchor.permalink.headerLink()
+      permalink: headerLink()
     },
 
     // @mdit-vue/plugin-toc のオプション

docs/ko/guide/markdown.md

@@ -944,15 +944,15 @@ VitePress는 마크다운 렌더러로 [markdown-it](https://github.com/markdown
 
 ```js
 import { defineConfig } from 'vitepress'
-import markdownItAnchor from 'markdown-it-anchor'
+import { headerLink } from '@mdit/plugin-anchor'
 import markdownItFoo from 'markdown-it-foo'
 
 export default defineConfig({
   markdown: {
-    // markdown-it-anchor의 옵션
-    // https://github.com/valeriangalliat/markdown-it-anchor#usage
+    // @mdit/plugin-anchor의 옵션
+    // https://mdit-plugins.github.io/anchor.html
     anchor: {
-      permalink: markdownItAnchor.permalink.headerLink()
+      permalink: headerLink()
     },
 
     // @mdit-vue/plugin-toc의 옵션

docs/pt/guide/markdown.md

@@ -906,15 +906,15 @@ VitePress usa [markdown-it](https://github.com/markdown-it/markdown-it) como int
 
 ```js
 import { defineConfig } from 'vitepress'
-import markdownItAnchor from 'markdown-it-anchor'
+import { headerLink } from '@mdit/plugin-anchor'
 import markdownItFoo from 'markdown-it-foo'
 
 export default defineConfig({
   markdown: {
-    // opções para markdown-it-anchor
-    // https://github.com/valeriangalliat/markdown-it-anchor#usage
+    // opções para @mdit/plugin-anchor
+    // https://mdit-plugins.github.io/anchor.html
     anchor: {
-      permalink: markdownItAnchor.permalink.headerLink()
+      permalink: headerLink()
     },
 
     // opções para @mdit-vue/plugin-toc

docs/ru/guide/markdown.md

@@ -1015,15 +1015,15 @@ VitePress использует [markdown-it](https://github.com/markdown-it/mark
 
 ```js
 import { defineConfig } from 'vitepress'
-import markdownItAnchor from 'markdown-it-anchor'
+import { headerLink } from '@mdit/plugin-anchor'
 import markdownItFoo from 'markdown-it-foo'
 
 export default defineConfig({
   markdown: {
-    // опции для markdown-it-anchor
-    // https://github.com/valeriangalliat/markdown-it-anchor#usage
+    // опции для @mdit/plugin-anchor
+    // https://mdit-plugins.github.io/anchor.html
     anchor: {
-      permalink: markdownItAnchor.permalink.headerLink()
+      permalink: headerLink()
     },
 
     // опции для @mdit-vue/plugin-toc

docs/zh/guide/markdown.md

@@ -907,15 +907,15 @@ VitePress 使用 [markdown-it](https://github.com/markdown-it/markdown-it) 作
 
 ```js
 import { defineConfig } from 'vitepress'
-import markdownItAnchor from 'markdown-it-anchor'
+import { headerLink } from '@mdit/plugin-anchor'
 import markdownItFoo from 'markdown-it-foo'
 
 export default defineConfig({
   markdown: {
-    // markdown-it-anchor 的选项
-    // https://github.com/valeriangalliat/markdown-it-anchor#usage
+    // @mdit/plugin-anchor 的选项
+    // https://mdit-plugins.github.io/anchor.html
     anchor: {
-      permalink: markdownItAnchor.permalink.headerLink()
+      permalink: headerLink()
     },
     // @mdit-vue/plugin-toc 的选项
     // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options

package.json

@@ -129,6 +129,7 @@
     "@mdit-vue/plugin-title": "^3.0.2",
     "@mdit-vue/plugin-toc": "^3.0.2",
     "@mdit-vue/shared": "^3.0.2",
+    "@mdit/plugin-anchor": "^1.1.1",
     "@polka/compression": "^1.0.0-next.28",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.3",
@@ -157,7 +158,6 @@
     "lodash.template": "^4.18.1",
     "lru-cache": "^11.5.1",
     "markdown-it": "^14.2.0",
-    "markdown-it-anchor": "^9.2.0",
     "markdown-it-async": "^2.2.0",
     "markdown-it-attrs": "4.3.1",
     "markdown-it-cjk-friendly": "^2.0.2",

patches/markdown-it-anchor@9.2.0.patch

@@ -1,17 +0,0 @@
-diff --git a/types/index.d.ts b/types/index.d.ts
-index 40c25c0be1add8b0fc2c51489c25a423dbc49d2c..807bc1b0e434d660c6a298b1dee1c87935bfac86 100644
---- a/types/index.d.ts
-+++ b/types/index.d.ts
-@@ -1,10 +1,8 @@
- import MarkdownIt from 'markdown-it';
--import { default as MarkdownItToken } from 'markdown-it/lib/token.mjs';
--import { default as MarkdownItState} from 'markdown-it/lib/rules_core/state_core.mjs';
-+import { default as Token } from 'markdown-it/lib/token.mjs';
-+import { default as State } from 'markdown-it/lib/rules_core/state_core.mjs';
- 
- declare namespace anchor {
--  export type Token = MarkdownItToken
--  export type State = MarkdownItState
-   export type RenderHref = (slug: string, state: State) => string;
-   export type RenderAttrs = (slug: string, state: State) => Record<string, string | number>;
- 

pnpm-lock.yaml

@@ -14,9 +14,6 @@ patchedDependencies:
   '@types/mdurl@2.0.0':
     hash: 3460e7d18ce390685cf4b8d8237fb20df9ad952c1336f479995a508a6395bfa4
     path: patches/@types__mdurl@2.0.0.patch
-  markdown-it-anchor@9.2.0:
-    hash: cdc28e7c329be30688ad192126ba505446611fbe526ad51483e4b1287aa35cf9
-    path: patches/markdown-it-anchor@9.2.0.patch
   markdown-it-attrs@4.3.1:
     hash: 12883b753541724964b5246a739df34c4b76db10415bbb63c35dce408cfe977e
     path: patches/markdown-it-attrs@4.3.1.patch
@@ -116,6 +113,9 @@ importers:
       '@mdit-vue/shared':
         specifier: ^3.0.2
         version: 3.0.2
+      '@mdit/plugin-anchor':
+        specifier: ^1.1.1
+        version: 1.1.1(markdown-it@14.2.0)
       '@polka/compression':
         specifier: ^1.0.0-next.28
         version: 1.0.0-next.28
@@ -200,9 +200,6 @@ importers:
       markdown-it:
         specifier: ^14.2.0
         version: 14.2.0
-      markdown-it-anchor:
-        specifier: ^9.2.0
-        version: 9.2.0(patch_hash=cdc28e7c329be30688ad192126ba505446611fbe526ad51483e4b1287aa35cf9)(@types/markdown-it@14.1.2)(markdown-it@14.2.0)
       markdown-it-async:
         specifier: ^2.2.0
         version: 2.2.0
@@ -643,6 +640,11 @@ packages:
     resolution: {integrity: sha512-00aAZ0F0NLik6I6Yba2emGbHLxv+QYrPH00qQ5dFKXlAo1Ll2RHDXwY7nN2WAfrx2pP+WrvSRFTGFCNGdzBDHw==}
     engines: {node: '>=20.0.0'}
 
+  '@mdit/plugin-anchor@1.1.1':
+    resolution: {integrity: sha512-42m7dxzvfLbo3YnteMB70aXFQ1TtnalyNLyPUDj5rr1FqTNf8pnHjQbgmf6FCjshg6BrfLVx7zpHJ7UUehQ/fA==}
+    peerDependencies:
+      markdown-it: ^14.2.0
+
   '@napi-rs/wasm-runtime@1.1.6':
     resolution: {integrity: sha512-ZLv/JdUfkvOy9eCnnBaGfiO+XimbjebAeO+MRQqD/B+FR1tnRN0tpKSJHRbE8sFfS6aqsXZ67TQjfwfsxULVbg==}
     peerDependencies:
@@ -2035,12 +2037,6 @@ packages:
   mark.js@8.11.1:
     resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==}
 
-  markdown-it-anchor@9.2.0:
-    resolution: {integrity: sha512-sa2ErMQ6kKOA4l31gLGYliFQrMKkqSO0ZJgGhDHKijPf0pNFM9vghjAh3gn26pS4JDRs7Iwa9S36gxm3vgZTzg==}
-    peerDependencies:
-      '@types/markdown-it': '*'
-      markdown-it: '*'
-
   markdown-it-async@2.2.0:
     resolution: {integrity: sha512-sITME+kf799vMeO/ww/CjH6q+c05f6TLpn6VOmmWCGNqPJzSh+uFgZoMB9s0plNtW6afy63qglNAC3MhrhP/gg==}
 
@@ -3239,6 +3235,11 @@ snapshots:
 
   '@mdit-vue/types@3.0.2': {}
 
+  '@mdit/plugin-anchor@1.1.1(markdown-it@14.2.0)':
+    dependencies:
+      '@types/markdown-it': 14.1.2
+      markdown-it: 14.2.0
+
   '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
     dependencies:
       '@emnapi/core': 1.11.1
@@ -4502,11 +4503,6 @@ snapshots:
 
   mark.js@8.11.1: {}
 
-  markdown-it-anchor@9.2.0(patch_hash=cdc28e7c329be30688ad192126ba505446611fbe526ad51483e4b1287aa35cf9)(@types/markdown-it@14.1.2)(markdown-it@14.2.0):
-    dependencies:
-      '@types/markdown-it': 14.1.2
-      markdown-it: 14.2.0
-
   markdown-it-async@2.2.0:
     dependencies:
       '@types/markdown-it': 14.1.2

pnpm-workspace.yaml

@@ -17,7 +17,6 @@ overrides:
 patchedDependencies:
   '@types/markdown-it-attrs': patches/@types__markdown-it-attrs@4.1.3.patch
   '@types/mdurl@2.0.0': patches/@types__mdurl@2.0.0.patch
-  markdown-it-anchor@9.2.0: patches/markdown-it-anchor@9.2.0.patch
   markdown-it-attrs@4.3.1: patches/markdown-it-attrs@4.3.1.patch
 
 shellEmulator: true

src/node/markdown/markdown.ts

@@ -14,13 +14,13 @@ import { sfcPlugin, type SfcPluginOptions } from '@mdit-vue/plugin-sfc'
 import { titlePlugin } from '@mdit-vue/plugin-title'
 import { tocPlugin, type TocPluginOptions } from '@mdit-vue/plugin-toc'
 import { slugify as defaultSlugify } from '@mdit-vue/shared'
+import { anchor as anchorPlugin, type AnchorOptions } from '@mdit/plugin-anchor'
 import type {
   CodeToHastOptions,
   LanguageInput,
   ShikiTransformer,
   ThemeRegistrationAny
 } from '@shikijs/types'
-import anchorPlugin from 'markdown-it-anchor'
 import { MarkdownItAsync, type MarkdownItAsyncOptions } from 'markdown-it-async'
 import attrsPlugin, { type MarkdownItAttrsOptions } from 'markdown-it-attrs'
 import mditCjkFriendly from 'markdown-it-cjk-friendly'
@@ -198,12 +198,12 @@ export interface MarkdownOptions extends MarkdownItAsyncOptions {
    */
   cjkFriendlyEmphasis?: boolean
   /**
-   * Options for `markdown-it-anchor`. Set to `false` to disable adding ids
+   * Options for `@mdit/plugin-anchor`. Set to `false` to disable adding ids
    * and anchor links to headings. Note that the default theme's outline and
    * heading hash links rely on these ids.
-   * @see https://github.com/valeriangalliat/markdown-it-anchor
+   * @see https://mdit-plugins.github.io/anchor.html
    */
-  anchor?: anchorPlugin.AnchorOptions | false
+  anchor?: AnchorOptions | false
   /**
    * Options for `@mdit-vue/plugin-headers`. Set to `true` or pass options
    * to collect page headers into page data.