文档页脚（VPDocFooter）的 Markdown 和 Edit 两个按钮没对齐，一高一低的。

[endless-bot]

🤖 Auto-generated by Endless task #27.

Initiated by: Huacnlee Li Huashun

背景

文档站（VitePress 2.0.0-alpha.16）每个文档页脚（VPDocFooter）展示两个操作链接：左侧的 Markdown 下载链接（.llms-text-link）和右侧的 "Edit this page" 按钮（.edit-link-button）。两者应水平排列、垂直居中对齐，但实际渲染中出现高低错位的视觉 bug，影响所有语言版本的每个文档页面。

该布局由自定义 CSS 控制：.VPDocFooter 被设置为 flex 容器（align-items: center），.edit-info 通过 display: contents 将子元素"提升"为直接 flex 子项，使 Markdown 链接与 Edit 按钮同层排列并居中对齐。这一方案在设计上是正确的，但实际未能生效。

根因

VitePress 2.0.0-alpha.16 VPDocFooter.vue 的 <style scoped> 在 ≥640px 视口下会为 .edit-info 注入 display: flex; padding-bottom: 14px，编译后的选择器为 .edit-info[data-v-xxxx]，CSS specificity = [0,2,0]。

项目 index.css 的覆写声明 .VPDocFooter > .edit-info { display: contents } specificity 同为 [0,2,0]。在相同 specificity 下，加载顺序靠后的声明胜出。VitePress 的 scoped 样式在 SSR 构建中可能晚于用户 CSS 注入，导致 display: flex 覆盖了 display: contents。

结果：.edit-info 保持 display: flex 并携带 padding-bottom: 14px（总高 46px），其子元素 .edit-link 的垂直中心 = 距顶 16px；而 .llms-text-link（line-height: 32px）作为兄弟 flex 子项在 46px 的容器空间中居中 = 距顶 23px。两者中心差 7px，呈现"一高一低"的视觉错位。

摘要

• 解决的问题：文档页脚 Markdown 链接与 Edit this page 按钮垂直中心不对齐（差约 7px）
• 做了什么：在 docs/.vitepress/theme/style/index.css 中为 .VPDocFooter > .edit-info 的 display: contents 声明添加 !important
• 为什么这样做：
  1. 原有 display: contents 的逻辑是正确的——只需确保它的优先级能稳定胜出 VitePress 的 scoped 样式；!important 是最小侵入式的修复，无需改变选择器结构。
  2. 备选方案"提升 specificity（如加 .VPContent）"可行，但需要了解运行时的具体 scoped hash 才能构造稳定的反向覆写，维护成本更高。
  3. 备选方案"修改 HTML 结构/Vue 组件"影响面更大，不符合"最小改动"原则。
• 如何验证：
  1. 本地运行 bun run dev，打开任意文档页（如 /docs/getting-started）
  2. 在 ≥640px 视口下，目测页脚 Markdown 链接与 "Edit this page" 按钮是否垂直居中对齐
  3. 在 <640px 视口下检查布局无破坏
  4. 切换深色模式确认样式一致
  5. 运行 bun run build:canary 构建后检查构建产物中同一页面的页脚渲染

修改

文件	改动内容
docs/.vitepress/theme/style/index.css	为 .VPDocFooter > .edit-info { display: contents } 添加 !important

关键决策

使用 !important 而非提升选择器 specificity：VitePress scoped 样式的 data-v-xxxx 哈希在每次构建时固定但对项目不透明，无法通过选择器覆写；!important 是 CSS 规范提供的唯一与加载顺序无关的优先级机制，在此场景下语义清晰——"这个值必须被项目覆写，不受框架样式影响"。