chore(deps-dev): bump vitepress from 2.0.0-alpha.17 to 2.0.0-alpha.20

[dependabot]

Bumps vitepress from 2.0.0-alpha.17 to 2.0.0-alpha.20.

Release notes

Sourced from vitepress's releases.

v2.0.0-alpha.20

Please refer to CHANGELOG.md for details.

v2.0.0-alpha.19

Please refer to CHANGELOG.md for details.

v2.0.0-alpha.18

Please refer to CHANGELOG.md for details.

Changelog

Sourced from vitepress's changelog.

2.0.0-alpha.20 (2026-09-04)

Bug Fixes

• harden eager frontmatter interpolation (#5413) (09f9672)
• key head entries by id and ignore meta content when deduping (b18f306), closes #5362 #5363 #5379
• search: respect per-locale markdown options (#5351) (27c4a1a)
• serialize config functions as code, not strings revived via new Function (close #3685) (d3b2957)
• theme/regression: fix misaligned external link icon (2be52f0)
• theme: adjust z-index for VPNavBar and simplify VPNavScreen styles (#5374) (35cf647)
• theme: cover the external link icon's paint box with its mask (39b8f9f)
• theme: drop the -webkit-backdrop-filter fallbacks (a2a0a92)
• theme: fix menu dropdown group dividers (#5365) (49c84f5)
• theme: fix nav screen and divider appearance (#5369) (a0401ee)
• theme: fix social links spacing in dropdown (#5370) (cb636b2)
• theme: handle outline bottom overscroll (#5375) (3fe901d)
• theme: keep search beside the title without a nav menu (14f4f09)
• theme: keep the search keycap glyphs out of the DOM text (60f656b), closes #5401
• theme: mark current navigation links (#5395) (0f0fe13)
• theme: paint the navbar divider on its own layer (9bebd09), closes #5399
• theme: prevent layout shifts when locking page scroll (310679a), closes #5386
• theme: prevent scroll chaining in local nav outline dropdown (#5367) (0a96bae)
• theme: remove extra margins from first and last paragraph inside a list element (8dbd782), closes #5353
• theme: render sidebar active state during ssr (005aa5c)
• theme: render sidebar group toggles as native buttons (ed2bfb2), closes #5366 #5371
• theme: rendering of sponsor and team components inside vp-doc containers (#4493) (b7602df)
• theme: treat negative scrollY as top (#5368) (9d521db)
• theme: use a getter as VPSidebar's open watch source (9aeeb4f)
• theme: use relative length units to auto-close nav screen menu (#5387) (c197979)

Features

• cli: make shortcuts case-insensitive (#5378) (4ffcdae)
• hashed icon styles, offline dev icons, arbitrary iconify collections (#5407) (d00a5e0)
• relative base (./) and assetsBase (CDN prefix) (#5406) (feadd9f)
• resolve $frontmatter expressions while rendering markdown (#5412) (a1eb284)
• ssr: enable throwUnhandledErrorInProduction (#5419) (a6573ff)
• theme: add --vp-local-nav-divider-color (110209d)
• theme: add opt-in severity-based colors for containers, alerts, and badges (#5373) (45cb85e)
• theme: redesign the navbar (#5397) (26b76d6)
• theme: scroll toc if active item is out of view (#5377) (72534af)
• theme: un-deprecate Theme.setup and compose it across extends (#5404) (ebbd48c)
• theme: use relative length units (#5323) (2a91caa)

2.0.0-alpha.19 (2026-08-02)

Bug Fixes

• build: apply rewrites when computing createContentLoader urls (9e2148d)
• build: clear markdown cache with rewritten path on include change (5eac447), closes #5035

... (truncated)

Commits

• 22b64ff release: v2.0.0-alpha.20
• dcf7fda chore: named imports don't work with json natively
• a6573ff feat(ssr): enable throwUnhandledErrorInProduction (#5419)
• 09f9672 fix: harden eager frontmatter interpolation (#5413)
• a1eb284 feat: resolve $frontmatter expressions while rendering markdown (#5412)
• 73bbaea chore: replace lodash.template with eta (#5411)
• 1a702fd docs: fix the appearance toggle example
• 7de3cae chore: generate third-party license notices for bundled deps (#5408)
• d00a5e0 feat: hashed icon styles, offline dev icons, arbitrary iconify collections (#...
• d3b2957 fix: serialize config functions as code, not strings revived via new Function...
• Additional commits viewable in compare view

[netlify]

✅ Deploy Preview for luxury-mochi-9269a9 ready!

Name	Link
🔨 Latest commit	27e710a
🔍 Latest deploy log	https://app.netlify.com/projects/luxury-mochi-9269a9/deploys/6abe696939ddf400081f8c5d
😎 Deploy Preview	https://deploy-preview-202--luxury-mochi-9269a9.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[YDX-2147483647]

人工智能对VitePress最近破坏性更改的分析

当前 vitepress@2.0.0-alpha.17（pnpm view 确认最新 2.x 为 2.0.0-alpha.20，dist-tag next；stable 仍是 1.6.4）。跨越 alpha.18 / .19 / .20 三版。大部分破坏性改动对本项目无影响，只有 2 项需要动手改，另有 3 项属于构建/视觉回归风险需人工确认。

---

一、确认需要修改（会实际破坏）

1. 脚注插件重复注册 —— 唯一确定的功能性破坏（alpha.19）

• 证据：src/node/markdown/markdown.ts（main 分支）已内置 @mdit/plugin-footnote，markdown.footnote 默认开启（if (options.footnote !== false) footnotePlugin(md)），注册位置在 tmp_md.ts:483；而用户的 markdown.config(md) 在 line 587 才执行，即晚于内置插件。
• 本项目 docs/.vitepress/config.ts:33 执行 md.use(footnote)（markdown-it-footnote@4），会在内置插件之后再挂一遍 footnote_ref / footnote_tail / footnote_inline 等同名 rule → 脚注被处理两次。
• 本项目确实在用 Markdown 脚注，不是死代码：
  • docs/FAQ/bib-csl.md:11,13（[^present]）
  • docs/FAQ/bib-etal-lang.md:91,94（[^url-link]）
  • docs/FAQ/mathcal_font.md:22,24,54,56（[^unicode-math]、[^unicode-math-cal]）
• 处理方式（二选一，推荐前者）：删除 md.use(footnote) 及 markdown-it-footnote、@types/markdown-it-footnote 依赖；或保留则设 markdown.footnote: false。顺带说明：docs/word.md:604 与 docs/FAQ/footnote-in-heading.md 里的 #footnote 是 Typst 代码，不受影响。

2. Netlify 构建环境需 Node ≥ 22（alpha.18）

• alpha.18 起 VitePress 使用 Vite 8 并放弃 Node 20 支持。
• package.json:23 已经是 vite: ^8.2.1，本地/CI Node 也是 v24（node --version = v24.14.1），GitHub Actions 用 actions/setup-node@v7 默认版本也没问题。
• 唯一风险点：netlify.toml 只有 command，没有 NODE_VERSION。升级前必须补上，否则 Netlify 默认镜像的 Node 可能低于 22 而构建失败。

---

二、无影响（已逐一核对配置与主题代码）

破坏性改动（alpha.18–20）	本项目情况
scrollOffset 移除、router.go 平滑滚动移除	config.ts 未设置；docs 内无 scroll-behavior/scroll-margin（已 grep）
useData().hash 移除	无使用；Layout.vue:15、SeeAlso.vue:7 已用 useRoute()
markdown.anchor 改为 @mdit/plugin-anchor 类型	未配置 markdown.anchor
markdown.attrs 选项重命名 / attrs.disable 移除	未使用
markdown.codeCopyButtonTitle → codeCopyButton.tooltipText	未使用；custom.css 只用 --vp-code-copy-code-bg，该变量未废弃
markdown.emoji.defs → definitions	未使用
markdown.image.lazyLoading → lazyLoad	未使用
cjkFriendly / lastUpdatedText / outlineTitle / disableDetailedView 移除	已是新写法：config.ts:154-164 用 outline.label 与 lastUpdated.text
Inter4CJK → Inter Core	custom.css 未自定义 --vp-font-family-base
include 内相对链接改为相对被包含文件解析（alpha.19）	唯一 include 在 docs/dev/index.md:67 → typst_template.ts（内容仅两行 Typst 设置，无链接/图片）
i18nRouting 函数第二参、build() 版本横幅、scaffold() 异步、normalize 重置	均未使用（未调用 build()，无 i18n）
markdown-it-attrs/-emoji/-anchor 被 @mdit/* 替换	项目未用这三个插件（markdown-it 仅作类型导入，mirror_link.ts:1）

---

三、需人工确认的回归风险（无 API 变更，但会改变产物/外观）

1. 构建从"记录错误"变为"直接失败" — alpha.20 ssr: enable throwUnhandledErrorInProduction。本项目在 SSR 期执行 <SeeAlso>（依赖 GitHub API，see_also.data.ts:44）、<Waline>、GitChangelog 虚拟模块；此前只打日志，现在任何 SSR 未捕获异常都会中断构建。check.yml:58-75 的 "default-minimal"（无 GH_TOKEN）任务最可能踩到。
2. 默认主题基础样式重写 — alpha.19 theme: rebuild the base styles on tailwind's preflight + normalize 重置差异（所有元素 margin/padding 归零、border-style: solid、hidden 加 !important、恢复 select/number 原生外观）；alpha.19 另有 use ul and li for lists、remove font-synthesis style、strip system-ui from font-family-base、route cjk punctuation to matching system fonts，alpha.17 起用 text-autospace / text-spacing-trim（项目在 custom.css:52 有 text-autospace: normal 覆盖）。本项目是中文排版重度定制站（custom.css 里大量 .vp-doc 覆盖、main .vp-doc h1 { display: none }、.vp-doc img 边距阴影），必须逐页比对排版。注：主题样式被包进 @layer __vitepress_base（alpha.16），未分层的 custom.css 仍可覆盖，但选择器权重变化仍可能影响结果。
3. 导航栏重设计 + 改用相对长度单位（alpha.20 redesign the navbar、use relative length units）——custom.css:14,23 覆盖了 --vp-nav-bg-color、--vp-nav-logo-height，需确认仍生效。
4. 次要：metaChunk 默认开启（alpha.19）、图标改为 hash 化的 iconify 样式（alpha.20，会改变产物文件名与缓存策略）、docs/dev/index.md:67 的 @include 在 alpha.19 后死链报错会带真实行号。
5. pnpm patch 可能失配：patches/@nolebase__vitepress-plugin-git-changelog.patch 改的是该插件自己的 dist，与 VitePress 版本无关；但升级后 @nolebase/vitepress-plugin-git-changelog 自身若也依赖被移除的 VitePress API，需要单独核对（本项目用了 repoURL: () => ... 回调形式）。

---

待查疑点（按要求暂停）

• markdown-it-footnote@4 与 @mdit/plugin-footnote 的 rule 名称是否完全一致——若一致则是"双执行"导致脚注重复渲染；若名称不同则是"互相不干扰但内置版本接管"，处理方式仍相同（移除 md.use），但影响描述需修正。
• mirror_link.ts:73 覆写 md.renderer.rules.link_open，与 alpha.18「base 应用于带 download 属性的链接」、alpha.19「social link 内部链接」等 link 相关改动是否有交互。
• Netlify 默认镜像的 Node 版本实际值（需在 Netlify 控制台或镜像文档确认）。