Skip to content

更新日志 ​

本页面记录了 VitePress 学习指南的重要更新和变更。

2026年09月12日 ​

🎨 首页 Hero 区域整体重建 ​

针对首页 Hero 存在的光晕与导航栏切割、统计条与下方模块重叠、整体错位等问题,放弃原有默认 VPHero 的脆弱两栏布局,改用自定义 HomeHero.vue 整体重建。

问题背景 ​

问题表现根因
光晕与导航栏切割顶部出现明显横向硬边默认 VPHero 两栏布局中 .image 的 translate(-2rem,-2rem) 偏移与负边距,加上背景层被 overflow:hidden 裁切,形成硬边界
统计条与 features 卡片重叠卡片被遮挡、文字发白隐藏的默认 .VPHero 仍带有 margin-top: calc(导航高度 * -1) 负外边距,把后续 features 整体上拉 64px,压到统计条上
整体错位、留白失衡标题与图片区不在同一基线依赖默认 VPHero 两栏网格,左文本列与右图片列权重不对齐

修复内容 ​

  • 新增 docs/.vitepress/theme/components/HomeHero.vue:采用 grid-template-columns: minmax(0,1.1fr) minmax(0,0.9fr) 的分栏结构,左侧内容(徽章行 + 渐变大标题 + 标语 + 单行内联打字机 + 操作按钮)、右侧视觉(同心光环 + Logo 立牌 + 漂浮技术标签 + 代码片段卡)、底部数据统计条,从源头消除错位。
  • docs/.vitepress/theme/components/HomeEnhance.vue:打字机由「胶囊 + 4 指示点」简化为单行内联,固定在标题与按钮之间,不再额外撑高。
  • docs/.vitepress/theme/styles/home.css:隐藏默认 VPHero 内容并归零其负外边距(margin-top: 0),消除对 features 的上拉遮挡;背景光晕层改用 mask-image 首尾渐隐,与导航栏及下方模块柔和过渡,不再叠加独立遮罩造成溢出。
  • docs/index.md:移除 hero.image 字段,Hero 视觉完全由 HomeHero.vue 控制。
  • docs/.vitepress/theme/index.ts:通过 home-hero-before 插槽挂载 HomeHero.vue。

验证方式 ​

  • vitepress build docs 构建成功(174 页全部生成)。
  • 产物 CSS 确认:VPHome .VPHero{margin-top:0} 位于默认规则之后、特异性相当,正确覆盖;.home-hero__bg 的 mask-image 首尾渐隐已生效。
  • 产物 HTML 确认 home-hero__* 结构完整渲染,默认 VPHero 容器已隐藏(无 has-image 类)。

🎨 无侧边栏页面导航栏搜索框对齐修复 ​

修复 /changelog、/contributing 等无侧边栏的顶层页面中,导航栏搜索框位置异常、与首页表现不一致的问题。

问题背景 ​

问题表现根因
搜索框位置异常搜索框被推离原位、浮在标题与菜单之间,并因 bg-alt 背景 + kbd 边框显得像一个孤立的框VitePress 默认规则 @media (min-width: 60rem) { .VPNavBar:not(.home) .title { min-width: calc(var(--vp-sidebar-width) - 2rem) } } 为所有非首页强行预留 15rem 标题列,用于与侧边栏对齐
右侧菜单被裁切6 个带图标的菜单项被挤到边缘并溢出裁切标题列被撑宽后,搜索框 margin-right:auto 吸收全部空隙,菜单被推至最右
与首页表现不一致首页(.home)标题保持自然宽度、搜索框紧贴标题,而文档页(无 has-sidebar)同样无侧边栏却被强制预留宽度项目采用路径键控侧边栏,/changelog、/contributing 等顶层页面 VPNavBar 类为 VPNavBar top(无 has-sidebar),但仍命中 :not(.home) 规则

修复内容 ​

  • docs/.vitepress/theme/styles/navigation.css:新增针对性覆盖,仅对无侧边栏页面取消标题列宽预留,使其与首页一致:
css
@media (min-width: 60rem) {
  .VPNavBar:not(.home):not(.has-sidebar) .title {
    min-width: 0;
  }
  .VPNavBar:not(.home):not(.has-sidebar) .content-body > .search {
    margin-right: auto;
  }
}

特异性 (0,4,0) 高于 VitePress 默认规则 (0,3,0),且编译位置在后,稳定生效;对有侧边栏页面(.has-sidebar)因 :not(.has-sidebar) 不匹配而保持原对齐,不受影响。

验证方式 ​

  • vitepress build docs 构建成功(174 页全部生成)。
  • 产物 CSS 确认覆盖规则 VPNavBar:not(.home):not(.has-sidebar) .title{min-width:0} 位于默认规则之后并正确注入。
  • 页面核验:/contributing、/changelog 的 VPNavBar 类为 VPNavBar top(无 sidebar)→ 标题恢复自然宽度、搜索框回原位;/guide/* 为 VPNavBar has-sidebar top → 保持 15rem 对齐,不受影响;首页 VPNavBar home top → 本就正常。

🎨 导航栏图标修复与定位机制重构 ​

修复导航栏一级与二级菜单图标显示异常,并将脆弱的位置选择器重构为稳定的 href 属性选择器。

问题背景 ​

导航图标采用 CSS mask-image + ::before 伪元素方案(原方案),但存在三类缺陷:

问题表现根因
首页导航栏无图标仅非首页显示图标useRouteStyles.ts 将 navigation.css 置于 if (!isHome) 分支,首页未加载该样式
一级菜单显示黑块全部菜单项为实心方块选择器误用直接子代 > .VPNavBarMenuLink,而 VitePress DOM 为 nav > ul > li > a,规则永不命中,仅通用规则的 background-color 生效
「更新日志」「贡献指南」缺图标二级菜单末两项为黑块下拉图标依赖 :nth-child(N) 位置选择器,顺序耦合脆弱,易错位或丢失

修复内容 ​

  • docs/.vitepress/theme/composables/useRouteStyles.ts:navigation.css 提升为全页面必加载(导航栏全局可见),并同步更新顶部分包策略注释。
  • docs/.vitepress/theme/styles/navigation.css:
    • 一级菜单 6 条图标规则由 > .VPNavBarMenuLink:nth-of-type(N) 改为 .list > li:nth-child(N) 后代选择器,并补充 mask-repeat / mask-size / mask-position 与 flex-shrink,消除实心黑块。
    • 全部 23 条下拉图标规则由 :nth-child 位置选择器重构为 href 属性选择器(如 [href$="/changelog"]),与菜单项一一对应,彻底消除顺序依赖,后续增删/调整菜单项不再错位或丢失图标。

验证方式 ​

  • vitepress build docs 构建成功,全部图标规则编译进入产物。
  • 从构建产物 HTML 提取「社区资源」下拉实际 href,与选择器逐条比对全部命中(含 /changelog、/contributing)。
  • 顶层导航 6 项 li:nth-child(1~6) 规则保持不变,验证可正常匹配。

2026年09月11日 ​

🔼 升级 VitePress 至 2.0.0-alpha.20 ​

将核心依赖 vitepress 从 2.0.0-alpha.19 升级到 2.0.0-alpha.20,同步更新新鲜度脚本的版本追踪基线。

⚠️ 破坏性变更适配(alpha.18 / alpha.19) ​

变更影响适配动作
升级 Vite 8、弃用 Node 20构建环境package.json 的 engines.node 由 >=18 改为 >=22
themeConfig.outlineTitle 删除大纲标题配置community/faq.md 示例改为 outline: { label: '目录' }
themeConfig.lastUpdatedText 删除更新时间文案改用 lastUpdated: { text: '...' }
markdown.cjkFriendly 删除CJK 排版改用 markdown.cjkFriendlyEmphasis
disableDetailedView 删除本地搜索改用 detailedView: false
markdown.codeCopyButtonTitle → markdown.codeCopyButton.tooltipText复制按钮文案迁移配置路径
scrollOffset 移除滚动偏移改用 CSS scroll-margin-top

项目 config.mts 经核查未使用任何已删除选项,升级后构建兼容,无需改动配置。

📝 文档内容同步 ​

  • guide/new-features.md:版本概览表补全 alpha.18 / alpha.19 / alpha.20;"当前使用版本"由 alpha.17 更正为 alpha.20;Breaking Changes 汇总表新增 12 条 alpha.18/19 破坏性变更。
  • community/faq.md:修正示例配置中已移除的 outlineTitle 写法。
  • docs/.vitepress/content-freshness.yml:版本追踪基线更新为 ^2.0.0-alpha.20。

🔧 仓库与站点地址统一 ​

  • package.json:repository.url 改为 https://cnb.cool/ZhangWeilong/VitePress,homepage 改为 https://vitepress.zhangweilong.com/。
  • docs/.vitepress/config.mts:SITE_URL 同步为 https://vitepress.zhangweilong.com/(canonical / OG / JSON-LD 一致)。

2026年05月09日 ​

✏️ 文档深度扩充 ​

对 4 篇关键文档进行全面深化,补充实战细节和 v2 新特性:

文件原行数扩充后核心新增内容
guide/migration-v2.md329~530v2 新特性一览表、CSS 变量完整映射表(v1→v2)、侧边栏/导航栏徽章、defineClientComponent/createContentLoader/isDark 新 API、暗色模式颜色迁移、搜索配置修复、useData 字段对比表、自动迁移脚本
advanced/cms-integration.md516~680修复 recursive: recursive: true 语法错误、Sanity 完整集成(Schema + GROQ + Portable Text)、Payload CMS 集成(Collection + Lexical)、原生数据加载器方案、Webhook CI 配置、环境变量汇总表
examples/component-docs.md771~870Monorepo 工作区结构、pnpm-workspace.yaml 配置、Props 自动生成三种方案(vue-component-meta / vue-docgen-api / 构建时虚拟模块)、组件沙箱集成(StackBlitz/CodeSandbox)、Monorepo CI 配置
ecosystem/plugins.md475~590插件生命周期流程图、发现渠道表、安装/更新/移除完整流程、版本策略与锁定建议、升级前检查清单、插件维护指南(命名/peerDependencies/变更日志/CI 多版本测试)、插件发布 10 步清单

🆕 新增实战案例 ​

文件标题行数难度核心内容
examples/collaborative-editing.md协同编辑实战案例~780高级Git 协作工作流、PR 模板与审核流程、CODEOWNERS、CI 自动化检查(Frontmatter 校验/死链/拼写)、PR 预览部署、贡献者自动生成与展示、智能编辑链接、内容发布检查、Headless CMS Webhook 同步

📝 文档内容扩充 ​

文件变更说明
best-practices/debugging.md新增常见错误速查表和 7 个场景14 种错误关键词速查表、Hydration Mismatch、ESM/CJS 冲突、v2 CSS 变量、Markdown 解析错误、侧边栏/导航栏不显示、搜索功能异常、静态资源 404
videos.md新增配套文字教程配套文字教程对照表(入门/进阶/实战三系列)、视频代码仓库说明、学习路线图(Mermaid 流程图 + 阶段规划表)、优化学习建议

⚙️ 配置更新 ​

  • 侧边栏 examples/ 实战案例新增「协同编辑实战」入口(带「新」标签)

2026年05月05日 ​

🔧 Markdown 格式规范修复 ​

代码块语言标识批量修复 ​

为 55 个文件 中的 129 个 代码块添加语言标识,确保符合 VitePress Markdown 规范:

修复项数量说明
添加 text 标识116目录结构、架构图、纯文本
添加 yaml 标识5YAML 配置内容
添加 js 标识3JavaScript 代码
添加 diff 标识2差异对比内容
添加 vue/html/bash 标识各 1Vue/HTML/Shell 代码
修复孤立闭合标记1examples/portfolio.md 多余的 ```

修复后统计:缺少语言标识的代码块从 129 个 降为 0 个。

重复标题合并 ​

best-practices/index.md 中两个重复的 ### 性能优化 表格合并为一个,包含 4 个条目。

死链修复 ​

修复 2 个死链:/advanced/using-vue(不存在)→ /advanced/components(正确路径)。

🆕 新增 7 篇深度文档 ​

文件标题行数难度核心内容
advanced/vite-config.mdVite 配置详解479高级Vite 选项、开发/构建/预览配置、插件集成、性能优化
advanced/markdown-it-plugins.mdMarkdown-it 插件扩展535高级插件开发、自定义语法、代码高亮扩展、构建集成
advanced/search-comparison.md搜索方案选型对比675进阶本地搜索 vs Algolia vs Pagefind vs 自定义,决策树
advanced/monorepo-docs.mdMonorepo 文档管理476高级Turborepo/Nx 集成、共享组件、多包文档策略
recipes/pdf-export.mdPDF 导出与离线文档418进阶Puppeteer 导出、离线包生成、自动化流程
theme/custom-homepage.md自定义首页开发1236进阶插槽扩展、完全自定义首页、动画组件、响应式设计
examples/multi-author-blog.md多作者博客搭建1133进阶作者管理、文章归属、团队展示、RSS 按作者

✏️ 文档内容扩充 ​

文件变更说明
guide/migration.md277 行 → 1051 行VuePress 迁移指南全面增强:9 步完整迁移流程、配置字段映射表、侧边栏自动转换脚本、Vue 2→3 组件迁移、插件对照表、自动化迁移脚本、难度升级为 Intermediate

⚙️ 配置更新 ​

  • 侧边栏 advanced/ 新增「Vite 配置详解」「Markdown-it 插件扩展」「搜索方案选型对比」入口(均带「新」标签)
  • 侧边栏 advanced/ 新增「工程化」分组,包含「Monorepo 文档管理」入口(带「新」标签)
  • 侧边栏 recipes/ 新增「PDF 导出与离线文档」入口(带「新」标签)
  • 侧边栏 theme/ 新增「自定义首页开发」入口(带「新」标签)
  • 侧边栏 examples/ 新增「多作者博客搭建」入口(带「新」标签)

🛠️ 工具脚本 ​

脚本说明
scripts/fix-code-langs.mjs自动检测并修复 Markdown 文件中缺少语言标识的代码块,支持 dry-run 模式

2026年04月11日 ​

🏷️ 标签详情页布局优化 ​

TagLayout.vue 全面升级,新增多项功能和暗色模式优化:

优化项变更
分类浏览模式新增「按分类浏览」模式(难度等级/功能模块/技术栈/应用场景/辅助功能/集成扩展)
排序功能支持按日期、难度、标题三种排序方式
标签描述为 28 个常用标签添加中文描述
文章统计页面头部新增文章数量徽标
搜索增强搜索框聚焦高亮、placeholder 颜色优化
结果统计搜索结果数量实时显示
暗色模式卡片阴影、搜索框聚焦、排序按钮、分类容器等暗色模式适配
文章数据新增「内容迁移工具」「暗色模式深度定制」「Markdown 最佳实践」等近期文章
过渡动画标签切换淡入过渡效果
搜索清空切换标签时自动清空搜索词

🎨 深色模式对比度优化 ​

对项目深色模式进行全面对比度和无障碍优化:

优化项变更
dark-mode.md 文档升级新增「对比度与无障碍」章节(WCAG 标准、检测工具、色觉适配)、「动态 theme-color」章节、「常见对比度问题修复」章节、「高对比度模式」章节、「深色模式设计原则」章节
动态 theme-colortheme/index.ts 新增 watch(isDark) 动态切换浏览器地址栏主题色
home.css.card-badge.hot 硬编码颜色改为 CSS 变量 var(--color-danger-soft) / var(--color-danger)
components.css.offline-indicator 硬编码颜色改为 CSS 变量 var(--color-warning)
variables.css新增暗色模式占位符、聚焦状态、禁用状态优化
检查清单从 10 项扩充至 13 项,新增 WCAG 对比度、动态 theme-color、色觉无障碍检查

🚀 VitePress 2.0 新特性专题文档 ​

将 guide/new-features.md 从概览级文档升级为完整专题文档(550 → 780+ 行),基于官方 CHANGELOG 逐版本梳理:

新增章节核心内容
版本概览补全 alpha.1 到 alpha.17 各版本主要变化
markdown-it-asyncmd.render → await md.renderAsync 迁移
分布式配置文件拆分配置到多个文件,自动合并
@layer 样式隔离alpha.16 样式优先级改进
useLayout 替代方案useLocalNav/useSidebar 迁移指南
postcssIsolateStyles 更新alpha.12 变更和迁移方法
动态路由重构alpha.3 HMR 改进
文本片段导航Text Fragments 协议支持
Shell $ 不可选alpha.14 复制体验优化
代码组切换事件vitepress:codeGroupTabActivate
完整 Breaking Changes 汇总10 项变更对照表
升级指南5 步安全升级流程

🆕 新增 8 篇深度文档 ​

文件标题难度核心内容
advanced/architecture.mdVitePress 原理与架构高级SSG 渲染流程、构建管线、插件机制
advanced/vite-ecosystem.mdVite 插件生态集成高级Vite 插件原理、常用插件集成、插件开发
advanced/vue-router.mdVitePress 与 Vue Router高级路由生成、客户端路由、动态路由
basics/markdown-best-practices.mdMarkdown 最佳实践进阶编写规范、性能优化、可维护性
community/code-of-conduct.md社区行为准则入门行为规范、举报流程、执行措施
community/community-projects.md社区项目展示入门项目分类、提交指南、案例集
guide/content-migration.md内容迁移工具进阶迁移脚本、批量转换、格式适配
theme/dark-mode.md暗色模式深度定制进阶CSS 变量适配、图片适配、组件适配

✏️ 文档内容扩充与完善 ​

入门指南:

文件变更
guide/installation.md新增「编辑器推荐」(VS Code 插件、推荐配置)和常见问题(镜像加速、权限、TypeScript 配置)
guide/project-structure.md新增「忽略文件配置」和常见问题(文件命名、图片存放、配置拆分)
guide/first-page.md新增常见问题(404、Frontmatter、代码块嵌套、Vue 组件渲染)

参考手册:

文件变更
reference/site-config.md新增 srcDir、srcExclude、outDir、cacheDir、ignoreDeadLinks 等配置选项
reference/runtime-api.md新增 useThemeData、usePageData、useFrontmatter、useSiteStore 等 API

教程模块:

文件变更
tutorial/index.md全面改版:新增学习路径概览(Mermaid 流程图)、「你将学到」列、三步学习法、学习建议扩充
tutorial/first-site.md新增 3 个进阶挑战、完善学习检查清单、新增常见问题
tutorial/deploy.md新增 3 个进阶挑战、部署检查清单、常见问题

社区板块:

文件变更
community/index.md新增「社区项目」「社区规范」章节,扩充快速入口表格(新增「适合谁」列)、活动类型、反馈渠道、贡献类型
community/roadmap.md更新 v1.2 已完成项(+7 项)、新增 v1.3 计划项、近期计划勾选 3 项完成、新增影响力指标

代码配方:

文件变更
recipes/comments.md新增「相关文档」提示框,链接到深度文章和教程
recipes/pwa.md新增「相关文档」提示框,链接到最佳实践和插件生态

文章归档:

文件变更
archive.md新增「按模块浏览」分类表格(入门指南、基础功能、主题定制、高级功能、最佳实践、社区)

🔧 配置与导航更新 ​

  • 侧边栏 community/ 新增「社区项目」「社区规范」分组
  • 侧边栏 guide/ 新增「内容迁移工具」入口(带「新」标签)
  • 侧边栏 basics/ 新增「Markdown 最佳实践」入口(带「新」标签)
  • 侧边栏 theme/ 新增「暗色模式深度定制」入口(带「新」标签)
  • 侧边栏 advanced/ 新增「VitePress 与 Vue Router」(带「新」标签)、「Vite 插件生态集成」(带「新」标签)、「底层原理」分组
  • 导航栏「社区资源」下拉新增「社区项目」和「在线演练场」链接
  • 修复社区资源下拉菜单图标(navigation.css):从 8 项扩展至 10 项,新增 folder/codepen 图标,调整 nth-child 索引

2026年04月10日 ​

📝 生态系统模块深度扩充 ​

大幅扩充生态系统模块的 7 篇集成方案文档,从概览级内容升级为完整实操指南:

文件原大小扩充后核心新增内容
ecosystem/comments.md~2.7 KB~15 KBGiscus/Waline/Twikoo/Artalk 完整集成代码、迁移指南
ecosystem/search.md~4.3 KB~14 KBPagefind/MeiliSearch 完整配置、搜索方案迁移指南
ecosystem/analytics.md~3.7 KB~13 KBSPA 追踪修复、Cookie 同意、事件追踪、多方案组合
ecosystem/deployment.md~3.6 KB~13 KBVercel/Netlify/CF Pages 完整配置、Docker 部署、检查清单
ecosystem/cms.md~3.0 KB~14 KBStrapi/Notion/Contentful/Sanity/TinaCMS 数据加载器代码
ecosystem/themes.md~5.1 KB~11 KB完整布局插槽表、主题迁移指南、主题发布流程
ecosystem/plugins.md~5.2 KB~11 KB代码复制/PWA/NProgress 配置、插件冲突排查

👥 社区板块内容扩充 ​

文件变更说明
community/faq.md8 → 30+ 问题从 8 个基础问题扩充至 30+ 个常见问题,覆盖安装配置、构建部署、样式主题、组件开发、SEO、性能等
community/events.md~2.6 KB → ~5 KB新增更多往期活动记录、分享主题建议、活动形式说明
新增 community/learning-resources.md—视频教程、精选文章、社区项目、工具资源汇总

🔧 配置更新 ​

  • 侧边栏 community/ 模块新增"学习资源"入口(带"新"标签)
  • 导航栏"资源"菜单新增"学习资源"链接(带"新"标签)

2026年04月08日 ​

🧹 内容清理与架构优化 ​

清理重定向页面:

  • 删除 advanced/api-config.md(已迁移至 /reference/site-config)
  • 删除 advanced/api-runtime.md(已迁移至 /reference/runtime-api)
  • 移除侧边栏 /advanced/ 下"API 参考(已迁移)"分组
  • 更新 12 处旧链接引用(文档正文、frontmatter prev/next、Vue 组件数据)

修复 frontmatter:

  • basics/assets.md 补充 updated 和 difficulty 字段
  • 修复 advanced/deployment.md frontmatter 损坏(wei--- → ---)

优化内容检查脚本:

  • scripts/content-freshness.mjs 跳过代码块和 frontmatter 区域,避免误报
  • "已废弃" 仅匹配提示框语境,"即将废弃" 跳过表格行
  • 移除 deprecated: 关键词(代码属性名,非待办事项)
  • 扫描结果:待办事项误报从 4 项降为 0

📊 Mermaid 图表深入教程 ​

新增 /docs/basics/mermaid.md:

图表类型用途
流程图业务流程、决策逻辑
序列图交互时序、API 调用
甘特图项目排期、里程碑
类图数据模型、继承关系
饼图占比分析、统计分布
状态图状态流转、生命周期
ER 图数据库设计、实体关系

还包含暗色主题适配、Vue 组件动态渲染、导出为 SVG 等进阶用法。

🔄 版本升级指南 ​

新增 /docs/guide/migration-v2.md:

内容说明
v1→v2 Breaking Changes配置、主题、构建三维度变更清单
升级检查清单30+ 检查项,分优先级
渐进式升级策略逐模块迁移,降低风险
回滚方案git 回退 + 配置备份

📦 生态系统扩充与去重叠 ​

扩充内容:

  • ecosystem/plugins.md — 新增插件选择标准、按功能分类表、冲突排查、Markdown-it 插件开发示例
  • ecosystem/themes.md — 新增主题选择决策树、功能对比表、迁移注意事项

去重叠精简(ecosystem/ 定位为选型概览,advanced/ 定位为深度教程):

文件修改策略
ecosystem/comments.md保留对比表+决策流程,删除完整组件代码,链接指向 advanced/
ecosystem/search.mdAlgolia 精简为快速配置,保留本地搜索/FlexSearch/Pagefind 独有内容
ecosystem/analytics.md保留对比表+快速配置,新增 Microsoft Clarity,链接指向 advanced/
ecosystem/deployment.md保留对比表+快速部署步骤,链接指向 advanced/
ecosystem/cms.md保留对比表+简介+数据流图,链接指向 advanced/
community/faq.md精简为 10 个最高频问题,链接指向 best-practices/faq

2026年04月07日 ​

📊 性能基准测试报告 ​

新增详细的性能基准测试文档 /docs/best-practices/performance-benchmark.md:

测试维度VitePressVuePressDocusaurus
构建时间 (200 页)8.2s15.6s23.4s
开发启动320ms1.2s2.1s
LCP0.8s1.2s1.5s
资源体积129 KB211 KB313 KB
Lighthouse98 分89 分82 分

包含内容:

  • 测试环境配置说明
  • 构建/开发/运行时性能对比
  • 不同网络条件测试
  • 压力测试报告
  • 本地自测指南

🏢 企业级案例研究 ​

新增企业级案例研究文档 /docs/examples/enterprise-case-study.md:

案例页面数团队规模月访问量
Vue.js 官方文档500+20+500 万+
Element Plus80+ 组件50+200 万+
企业知识库2000+55000 用户
VueUse200+ 函数10+18K Stars

包含内容:

  • 企业级需求分析框架
  • 4 个深度案例解析
  • 企业级最佳实践
  • 选型决策建议

🔧 故障排查手册完善 ​

更新 /docs/best-practices/error-handling.md:

  • 新增 错误代码速查表(20+ 常见错误码)
  • 新增 场景排查指南(构建失败、运行时错误、部署问题)
  • 新增 诊断工具箱(日志分析、环境检查)

📦 迁移专题指南更新 ​

更新 /docs/guide/migration-other.md:

  • 新增 6 种工具迁移方案(VuePress、Docusaurus、Docsify、GitBook、Hexo、JSDoc)
  • 新增预计迁移时间
  • 新增迁移决策树

📚 模块索引页面扩充 ​

文件新增内容
ecosystem/index.md工具选择指南、决策流程图
reference/index.mdAPI 速查表、配置模板
recipes/index.md配方分类表、使用场景

🏷️ Tags 风格统一 ​

制定标签命名规范并修复不一致:

修复项原值修复后
技术名词大小写vitepress、vueVitePress、Vue
中英文格式API文档API 文档

新增 tags.md 标签风格规范章节:

  • 英文标签首字母大写规则
  • 中文标签命名规范
  • 中英文混合格式规则

📝 Frontmatter 元数据完善 ​

文件补充内容
404.md添加 description
tutorial/index.md补充完整 frontmatter

📄 项目说明文件更新 ​

更新 README.md:

  • 新增性能基准测试、企业级案例统计项
  • 更新最佳实践列表
  • 更新路线图已完成项(9 项)

📑 目录索引页面完善 ​

为 5 个主要模块添加索引页面,提升导航体验:

文件内容概要
guide/index.md入门指南模块索引,包含快速开始、安装配置等
basics/index.md基础功能模块索引,包含 Markdown、路由、导航等
theme/index.md主题定制模块索引,包含自定义主题、布局插槽等
advanced/index.md高级功能模块索引,包含国际化、数据加载、部署等
best-practices/index.md最佳实践模块索引,包含性能优化、SEO、安全等

优化效果:

  • 侧边栏导航支持模块首页跳转
  • 模块内容概览一目了然
  • 支持快速定位所需内容

👥 社区板块内容扩充 ​

新增 3 个社区页面,完善社区生态:

文件内容
community/events.md社区活动、线上会议、线下聚会信息
community/roadmap.md项目路线图、版本规划、功能展望
community/contributing-guide.md贡献指南、开发流程、代码规范

🔧 Markdown 格式规范修复 ​

批量修复不符合 VitePress 标准的 Markdown 格式:

表格格式修复 ​

将非标准 ||---| 格式修正为 |---|,涉及 11 个文件:

目录修复文件数
community/1
ecosystem/1
tutorial/1
reference/1
examples/1
guide/2
advanced/1
basics/1
best-practices/2

代码块语言标识修复 ​

为目录结构代码块添加 text 语言标识,涉及 6 个文件:

  • tutorial/first-site.md
  • tutorial/deploy.md
  • tutorial/custom-theme.md
  • tutorial/component-docs.md
  • tutorial/i18n.md
  • changelog.md

🔗 教程导航链接完善 ​

为 11 个教程页面添加 prev/next 导航链接:

text
first-site → installation → navigation → theme-colors → 
custom-theme → custom-layout → component-docs → blog → 
comments → i18n → plugin-dev → deploy

⚙️ 配置文件更新 ​

更新 config.mts 侧边栏配置:

  • 新增社区板块导航项(活动、路线图、贡献指南)
  • 优化侧边栏分组结构

2026年04月06日 ​

📝 内容优化 ​

重复文档清理 ​

清理了 /advanced/ 目录下的重复 API 文档,简化为重定向页面:

文件修改前修改后
advanced/api-config.md412 行完整内容30 行重定向页面
advanced/api-runtime.md382 行完整内容31 行重定向页面

优化效果:

  • 消除了与 /reference/ 目录下文档的内容重复
  • 用户访问旧链接时会看到明确的迁移提示
  • 使用 <VPLink> 组件提供美观的跳转卡片

🌐 生态系统模块完善 ​

补全生态系统模块的集成方案文档,新增 5 篇完整文档:

文件内容
ecosystem/comments.md评论系统对比(Giscus、Waline、Twikoo)与集成指南
ecosystem/search.md搜索服务方案(本地搜索、Algolia、DocSearch、FlexSearch)
ecosystem/analytics.md数据统计方案(Google Analytics、百度统计、Umami、Plausible)
ecosystem/deployment.md部署平台选择(Vercel、Netlify、GitHub Pages、Cloudflare、Railway、Zeabur)
ecosystem/cms.mdCMS 集成方案(Strapi、Notion、Contentful、Sanity、TinaCMS)

文档特点:

  • 每篇文档包含完整的功能对比表格
  • 提供详细的安装配置步骤
  • 包含代码示例和最佳实践建议
  • 支持快速选择和决策流程图

📐 示例页面完善 ​

完善 4 个简略示例页面,补充完整的实现代码:

文件原内容新内容
examples/blog-list-demo.md16 行简单说明完整布局组件、数据加载器、使用示例
examples/about-demo.md35 行简单说明完整个人信息布局、统计数据、社交链接
examples/links-demo.md21 行简单说明完整友链管理、申请说明、网格布局
examples/projects-demo.md16 行简单说明项目展示、标签筛选、响应式网格

新增内容:

  • Vue 组件完整实现代码
  • 数据加载器配置示例
  • 响应式样式和动画效果
  • 深色模式适配方案

📊 内容架构审计 ​

完成网站内容架构完整性审计:

审计项状态说明
内容架构✅ 优秀11 个模块覆盖完整
Markdown 格式✅ 规范符合 VitePress 标准
文件完整性✅ 完善生态系统文件已补全
内容质量✅ 完善示例页面已充实
学习路径✅ 完善5 阶段路径清晰
实战案例✅ 丰富9 种类型案例

2026年04月04日 ​

🎨 导航栏图标增强 ​

为导航栏添加完整的 SVG 图标支持,提升视觉体验:

导航项图标说明
首页home房屋图标
学习指南book书本图标
参考手册fileText文档图标
生态系统grid网格图标
最佳实践award奖章图标
社区资源users用户组图标

下拉菜单图标(14x14 小图标):

菜单项图标
快速上手rocket
学习路径map
入门指南compass
基础功能layers
主题定制palette
高级功能cpu
实战案例briefcase
交互式教程graduationCap
API 参考code
代码配方terminal
插件市场package
主题市场layout
集成方案zap
常见问题helpCircle
案例展示image
视频教程play
学习资源folder
标签分类tag
文章归档archive
更新日志history
贡献指南heart

实现方式:

  • 使用 CSS ::before 伪元素 + mask-image 实现
  • 主导航图标尺寸 16x16,下拉菜单图标尺寸 14x14
  • 图标通过 nth-of-type 选择器精确匹配导航项
  • 悬停/激活状态自动变色,图标与配置分离,便于维护

📚 新模块内容补充完成 ​

完成 5 个新模块共 42 篇完整文档的编写,所有占位页面均已补充完整内容:

模块文件数主要内容
/reference/8 篇站点配置、运行时 API、构建 API、CLI 命令、Frontmatter 配置、主题配置、主题 API
/recipes/17 篇布局配方(404/顶部按钮/导航栏/页脚)、功能配方(评论/搜索/阅读统计)、内容配方(侧边栏/标签/归档)、集成配方(GA/RSS/PWA/Sitemap)
/ecosystem/3 篇插件市场、主题市场、集成方案索引
/tutorial/12 篇入门系列(创建站点/导航/部署)、样式定制(颜色/布局/主题)、功能扩展(博客/评论/多语言)、高级实战(插件开发/组件文档)
/community/2 篇FAQ 问答、社区索引

文档特点:

  • 所有文档包含完整 frontmatter 元数据
  • 大量代码示例和配置片段
  • 实用的最佳实践建议
  • 相关链接和参考资源

🗂️ 目录结构重构 ​

为支持内容扩展,进行了大规模的目录结构调整:

新增模块:

模块目录说明
API 参考/reference/配置参考、运行时 API、CLI 命令
代码配方/recipes/常见需求的快速解决方案
生态系统/ecosystem/插件市场、主题市场、集成方案
交互式教程/tutorial/分步骤的动手实践教程
社区/community/常见问题、贡献指南

导航栏调整:

从 4 个主导航扩展为 6 个:

text
首页概览 | 学习指南 | 参考手册 | 生态系统 | 最佳实践 | 社区

新增文档数量:

  • 新增索引文件:5 个
  • 新增占位页面:32 个
  • 更新配置项:侧边栏 5 个、导航 6 个、结构化数据映射 6 个

📖 API 文档迁移 ​

将 advanced/ 中的 API 文档迁移整合到 reference/ 模块:

原位置新位置说明
/advanced/api-runtime/reference/runtime-api运行时 API 完整文档
/advanced/api-config/reference/site-config站点配置完整文档

更新内容:

  • 运行时 API 文档:useData、useRoute、useRouter、usePrefetch、withBase、defineClientComponent、Content 组件
  • 站点配置文档:基础配置、Head 配置、Markdown 配置、主题配置、构建钩子、Vite 配置
  • 侧边栏链接更新:advanced 模块中的 API 参考指向新位置
  • 旧文档添加迁移提示

📖 核心文档扩充 ​

大幅扩充「什么是 VitePress」文档,内容从 2.8KB 扩展到约 15KB:

新增内容说明
技术架构图ASCII 架构图展示 VitePress 技术栈组成
工作流程开发模式和生产构建的详细流程说明
详细对比矩阵与 VuePress/Docusaurus/Nuxt Content/Next.js 的全方位对比
选型建议不同场景下的工具选择建议
性能对比开发启动、热更新、构建时间的基准数据
发展历程版本演进时间线
决策矩阵需求对照表帮助判断是否适用
检查清单扩展新增技术掌握类检查项

📄 占位页面完善 ​

完善了两个占位页面的内容,使其成为完整可用的功能页面:

页面文件主要更新
文章归档docs/archive.md使用说明、归档统计、学习建议、时间线说明
标签详情docs/tag.md标签选择方法、分类体系、热门标签速览、组合技巧

导航更新:

  • 资源中心菜单新增「文章归档」入口
  • 更新 activeMatch 模式以匹配新路由

📖 FAQ 内容扩展 ​

大幅扩展常见问题文档,新增以下分类:

分类新增问题数覆盖内容
PWA 深度问题5Service Worker、图标、iOS、离线、缓存策略
动画与交互3页面过渡、滚动揭示、动画偏好
数据加载2动态数据、构建时数据
评论系统2Giscus、Waline 配置
图片优化2加载优化、路径问题
RSS 订阅2生成配置、内容格式
无障碍访问3键盘导航、屏幕阅读器、颜色对比度
调试排错3构建分析、开发调试、错误捕获
快速参考3常用命令、配置路径、错误速查表

新增问题示例:

  • Service Worker 更新策略详解
  • PWA 图标完整配置
  • iOS PWA 适配方案
  • 缓存策略最佳实践
  • 评论系统集成问题
  • 无障碍访问指南

🎨 首页 Hero 增强 ​

为首页 Hero 区域添加动态视觉效果,提升用户体验:

功能说明
粒子背景Canvas 绘制的动态粒子网络,支持鼠标交互
渐变光晕浮动的渐变光球,增加层次感
打字机效果增强的打字机动画,带指示器和暂停高亮
深色适配所有效果均适配深色模式
动画减少支持 prefers-reduced-motion 媒体查询

新增组件:

  • docs/.vitepress/theme/components/ParticleBackground.vue - 粒子背景
  • docs/.vitepress/theme/components/HeroBackground.vue - Hero 背景包装器

更新组件:

  • docs/.vitepress/theme/components/HomeEnhance.vue - 增强打字机效果

技术实现:

  • 粒子使用 Canvas 2D API 绘制,支持连线效果
  • 鼠标移动时粒子会被排斥,产生交互感
  • 渐变光球使用 CSS 动画浮动
  • 打字机效果添加了标签指示器和暂停高亮状态

📱 PWA 图标 ​

新增完整的 PWA 图标支持,提供更好的移动端安装体验:

图标文件尺寸用途
pwa-192x192.png192×192Android 图标
pwa-512x512.png512×512Android 大图标
apple-touch-icon.png180×180iOS 主屏幕图标
safari-pinned-tab.svg矢量Safari 固定标签图标
favicon.ico48×48浏览器标签图标

更新内容:

  • 使用 sharp 从 SVG 源文件自动生成 PNG 图标
  • 更新 PWA manifest 配置,使用 PNG 图标替代 SVG
  • 添加完整的 iOS Safari meta 标签支持
  • 优化图标设计,添加渐变背景和阴影效果

新增脚本:

  • scripts/generate-pwa-icons.mjs - PWA 图标生成脚本

新增依赖:

  • sharp - 高性能图片处理库

🧪 测试覆盖 ​

布局组件单元测试 ​

新增 6 个布局组件的单元测试,测试用例总数从 152 个扩展到 313 个:

项目说明
测试框架Vitest 4.1.2
测试环境happy-dom
测试工具@vue/test-utils 2.4.6
覆盖率@vitest/coverage-v8
测试文件19 个测试文件
测试用例313 个测试用例

新增布局测试:

布局组件测试数覆盖内容
AboutLayout28个人信息卡片、技能展示、工作经历、社交链接
BlogListLayout24文章列表、标签筛选、搜索功能、分页
LinksLayout23友链分类、链接卡片、申请友链区域
ProjectsLayout29项目筛选、精选项目、状态切换、标签过滤
ArchiveLayout26时间线渲染、年份折叠、搜索功能、统计信息
TagLayout31标签选择、URL 同步、文章过滤、图标颜色映射

新增测试文件:

  • docs/.vitepress/theme/layouts/AboutLayout.test.ts
  • docs/.vitepress/theme/layouts/BlogListLayout.test.ts
  • docs/.vitepress/theme/layouts/LinksLayout.test.ts
  • docs/.vitepress/theme/layouts/ProjectsLayout.test.ts
  • docs/.vitepress/theme/layouts/ArchiveLayout.test.ts
  • docs/.vitepress/theme/layouts/TagLayout.test.ts

核心组件单元测试扩展 ​

新增 7 个核心组件的单元测试,测试用例总数从 48 个扩展到 152 个:

项目说明
测试框架Vitest 4.1.2
测试环境happy-dom
测试工具@vue/test-utils 2.4.6
覆盖率@vitest/coverage-v8
测试文件13 个测试文件
测试用例152 个测试用例

新增测试组件:

组件测试数覆盖内容
StructuredData6JSON-LD 结构验证、Schema 类型检测
KnowledgeGraph15节点渲染、边连线、交互事件、布局计算
LearningChecklist15进度追踪、localStorage 持久化、重置功能
QuizComponent21问题导航、答案验证、计分系统、完成状态
KeyboardShortcuts16快捷键响应、帮助弹窗、首次访问提示
DocFeedback16有帮助/无帮助反馈、详细反馈表单、持久化
GlobalFooter15布局类型切换、备案信息、返回顶部

新增测试文件:

  • docs/.vitepress/theme/components/StructuredData.test.ts
  • docs/.vitepress/theme/components/KnowledgeGraph.test.ts
  • docs/.vitepress/theme/components/LearningChecklist.test.ts
  • docs/.vitepress/theme/components/QuizComponent.test.ts
  • docs/.vitepress/theme/components/KeyboardShortcuts.test.ts
  • docs/.vitepress/theme/components/DocFeedback.test.ts
  • docs/.vitepress/theme/components/GlobalFooter.test.ts

📝 内容更新 ​

组件单元测试环境 ​

配置 Vitest 测试框架,为核心组件编写单元测试:

项目说明
测试框架Vitest 4.1.2
测试环境happy-dom
测试工具@vue/test-utils 2.4.6
覆盖率@vitest/coverage-v8
测试文件6 个测试文件
测试用例48 个测试用例

已测试组件:

组件测试数覆盖内容
BackToTop7渲染、显示/隐藏、滚动监听、点击事件
CopyToast7渲染、显示/隐藏、定时器、事件监听
ProgressBar9渲染、进度计算、边界条件
LikeButton10渲染、点赞/取消、localStorage、动画
ReadingTime8渲染、计算逻辑、DOM 插入
useRouteStyles7函数调用、路径处理

新增文件:

  • vitest.config.ts - Vitest 配置
  • docs/.vitepress/theme/test/setup.ts - 测试环境设置
  • docs/.vitepress/theme/components/*.test.ts - 组件测试
  • docs/.vitepress/theme/composables/*.test.ts - Composable 测试

测试命令:

  • npm run test - 运行测试(watch 模式)
  • npm run test:run - 运行测试(单次执行)
  • npm run test:coverage - 生成覆盖率报告

深色模式对比度优化 ​

全面优化深色模式的颜色对比度,符合 WCAG AA 标准:

优化项目说明
文本颜色主文本 92% 不透明度,对比度 ≥ 4.5:1
品牌颜色主色 #a5b4fc,对比度 ~8.5:1
背景层次三级背景色(#0f0f10 / #18181b / #27272a)
语义色成功/警告/危险/信息色亮度提升
代码块代码背景、文字、高亮优化
自定义容器边框、背景、文字颜色优化
表格边框、斑马纹颜色优化
链接颜色和悬停状态优化
滚动条深色滚动条样式
选中文字高亮颜色优化
高对比度模式支持 prefers-contrast: more
减少动画支持 prefers-reduced-motion

修改文件:

  • docs/.vitepress/theme/styles/variables.css - 深色模式变量扩展
  • docs/.vitepress/theme/styles/accessibility.css - 无障碍优化增强

归档页布局 ​

新增 ArchiveLayout.vue 归档页布局:

功能说明
时间线视图按年份分组展示文章
年份折叠可展开/折叠各年份
搜索过滤搜索标题、摘要、标签
统计信息总文章数、年份数等
响应式移动端适配

创建页面 /archive.md。

标签详情页布局 ​

新增 TagLayout.vue 标签详情页布局:

功能说明
标签筛选从 URL hash 获取标签,自动筛选文章
标签云显示所有标签及文章数量
搜索在当前标签中搜索文章
标签图标为 50+ 标签配置专属图标
标签颜色为热门标签配置专属颜色
响应式移动端适配

创建页面 /tag.md,更新 /tags.md 链接指向新页面。

VitePress 2.0 新特性专题文档 ​

完全重写 /guide/new-features.md 文档,基于官方 CHANGELOG 整理:

新增章节主要内容
核心升级Vite 6/7 支持、Shiki v3 升级
Markdown 增强CJK 友好、数学公式、代码片段、GitHub 警告
搜索增强本地搜索优化、DocSearch v4
主题定制CSS 变量系统、新布局插槽、首页配置
路由导航路由重写、路由器增强、导航增强
多语言语言菜单增强、文本自动间距
性能优化构建优化、运行时优化、按需加载
新增 API站点配置、构建钩子、组合式 API
Breaking Changes配置变更、主题变更、Markdown 变更
升级指南依赖更新、配置检查、主题更新

FAQ 内容扩展 ​

扩展了 /best-practices/faq.md 文档,新增 6 大分类共 20+ 个问题:

新增分类主要内容
组件开发SSR 兼容、样式隔离、动态导入
插件相关自定义插件开发、常用插件推荐
SEO 相关结构化数据、sitemap、robots.txt
环境变量多环境配置、组件中使用环境变量
部署平台Vercel/Netlify/Cloudflare Pages 配置
常见报错Hydration mismatch、模块导入失败等
安全相关XSS 防护、敏感信息保护
样式相关主题覆盖、深色模式、移动端适配

CSS 变量文档扩展 ​

扩展了 /theme/css-variables.md 文档,新增以下内容:

新增内容说明
本项目自定义变量间距、圆角、阴影、语义色系统
间距系统--space-xs 到 --space-2xl 共 6 级间距
圆角系统--radius-sm 到 --radius-full 共 5 级圆角
阴影系统--shadow-sm 到 --shadow-xl 共 4 级阴影(含深色模式适配)
语义色系统成功、警告、危险、信息 4 种语义色及其柔和背景
变量速查表颜色、布局、扩展变量快速参考表格
使用示例每类变量附带实际应用代码示例

README 项目说明更新 ​

更新了项目说明文档:

更新项说明
简介部分改为表格形式展示统计数据(教程数、组件数等)
工程能力新增 5 项功能说明(按需样式加载、键盘快捷键等)
项目路线图新增章节,分为已完成/进行中/计划中三部分
项目结构添加 composables/ 目录说明,补充完整组件列表
导航链接新增"路线图"快捷链接

📋 项目路线图 ​

已完成 ✅ ​

进行中 🚧 ​

计划中 📋 ​


2026年04月03日 ​

✨ 新增功能 ​

新手引导页 ​

新增 /getting-started 新手引导页面,帮助用户 5 分钟快速上手 VitePress:

内容说明
核心特点介绍7 大核心特性表格说明
适用场景判断适用 / 不适用场景对比
工具横向对比与 Docusaurus、Nuxt Content、Docsify、VuePress 对比
决策树如何选择文档工具的流程图
环境检查清单Node.js、npm 等环境要求自检
三步快速上手创建项目 → 启动 → 编写内容
推荐学习路径零基础 / 迁移 / 进阶三条路径
学习小贴士高效学习建议和常见误区

🚀 性能优化 ​

样式文件拆分与首屏加载优化 ​

将 style.css (30.87KB) 拆分为 16 个 模块化样式文件,优化首屏加载性能:

优化项说明
首屏样式减少关键样式从 30.87KB 减少至 ~17.5KB,减少 43%
加载策略优化按优先级分级加载:关键样式同步、非关键样式延迟
缓存效率提升模块化文件独立缓存,修改一个模块不影响其他文件

新的样式文件结构 ​

文件大小(约)说明
variables.css2KBCSS 变量(品牌色、间距、阴影等)
buttons.css0.5KB按钮样式
navigation.css12KB导航样式(图标、下拉菜单)
typography.css1KB排版样式(标题、段落、链接)
code.css2KB代码块样式
tables.css1KB表格样式
custom-blocks.css3KB自定义容器样式
toc.css1KB目录样式
utilities.css2KB工具类样式
animations.css5KB动画效果
responsive.css1KB响应式适配
accessibility.css1KB无障碍优化
print.css3KB打印样式

加载策略说明 ​

typescript
// 1. 关键样式(首屏必需,同步加载,~17.5KB)
import './styles/variables.css'      // CSS 变量(立即生效)
import './styles/buttons.css'        // 按钮交互
import './styles/navigation.css'     // 导航功能
import './styles/typography.css'     // 内容排版
import './styles/code.css'           // 代码展示

// 2. 页面组件样式(中等优先级)
import './styles/tables.css'
import './styles/custom-blocks.css'
import './styles/toc.css'
import './styles/utilities.css'

// 3. 非关键样式(可延迟加载)
import './styles/animations.css'
import './styles/responsive.css'
import './styles/accessibility.css'
import './styles/print.css'

Critical CSS 内联 ​

将首屏关键样式(9.9KB)内联到 HTML <head> 中,消除渲染阻塞的 CSS 请求:

优化项说明
内联大小9.9KB / 页(压缩后的关键样式)
覆盖页面98 个 HTML 页面全部注入
包含内容CSS 变量、按钮、导航栏/侧边栏、排版、代码块
构建集成npm run build 自动执行注入脚本

新增文件:

文件说明
styles/critical.cssCritical CSS 聚合入口(@import 5 个关键模块)
scripts/inject-critical-css.mjs构建后处理脚本(自动内联到所有页面)

工作流程:

bash
# 1. 构建项目
npm run build
#   ↓ 自动执行
# 2. 注入 Critical CSS 到所有 HTML <head>
node scripts/inject-critical-css.mjs

# 也可单独运行:
npm run build          # 仅构建(不注入)
node scripts/inject-critical-css.mjs  # 单独注入

🎯 交互式功能 ​

学习检查清单组件 ​

新增 LearningChecklist 全局 Vue 组件,为每篇教程提供交互式知识点跟踪:

功能说明
分组展示按知识模块分组(如概念理解、环境准备、项目创建)
进度追踪实时显示完成进度条和百分比
持久化存储使用 localStorage 保存学习进度,刷新不丢失
资源链接每个检查项可附带关联资源跳转
重置功能一键重置当前章节的学习进度

组件特性:

特性说明
自定义复选框美观的动画勾选效果
完成状态全部完成后显示庆祝提示 ✨
响应式设计适配移动端和桌面端
深色模式自动跟随 VitePress 主题色变量

已集成检查清单的教程:

教程检查项数存储键
什么是 VitePress (/guide/what-is-vitepress)5 项checklist-vp-intro
安装与环境配置 (/guide/installation)9 项checklist-installation
Markdown 扩展语法 (/basics/markdown)13 项checklist-markdown
组件使用 (/advanced/components)12 项checklist-components

使用方式:

markdown
<script setup>
const checklist = [
  {
    title: '分组标题',
    items: [
      { id: 'unique-id', task: '任务描述', resources: [{ label: '参考文档', link: '/path' }] }
    ]
  }
]
</script>

<LearningChecklist title="本章检查清单" :groups="checklist" storage-key="checklist-xxx" />

新增/修改文件:

文件操作说明
theme/components/LearningChecklist.vue新增学习检查清单组件(~260 行)
theme/index.ts修改异步导入 + 注册全局组件
guide/what-is-vitepress.md修改添加 5 项入门概念检查清单
guide/installation.md修改添加 9 项安装配置检查清单
basics/markdown.md修改添加 13 项 Markdown 语法检查清单
advanced/components.md修改添加 12 项组件开发检查清单

📝 文档更新 ​

文档说明
styles/README.md新增样式架构说明文档,包含优化策略和使用指南

📄 元数据完善 ​

批量补充 Frontmatter 字段 ​

为 92 个文档 批量补充了 SEO 和结构化数据所需的元数据字段:

新增字段值说明
authorVitePress 学习指南统一作者信息
date2026-01-15(已有则保留)文章发布日期
updated同 date 或保留原值最后更新时间
difficulty按目录自动推断Beginner / Intermediate / Advanced

难度等级分配规则:

目录难度文件数
guide/ + basics/Beginner23 篇
best-practices/ + theme/ + examples/Intermediate40 篇
advanced/Advanced19 篇

排除文件:首页、404、布局演示页等非教程页面

🔍 SEO 优化 ​

JSON-LD 结构化数据集成 ​

在 config.mts 的 transformHead 中为每个页面动态生成 JSON-LD 结构化数据:

Schema 类型说明适用页面
WebSite站点级搜索动作所有页面
TechArticle技术文章(含分类、难度、关键词)文档页(非首页)
BreadcrumbList面包屑导航路径所有页面

结构化数据特性:

  • 自动推断文章分类:从 URL 路径自动匹配所属模块
  • 动态字段映射:读取 frontmatter 中的 title、description、date、updated、difficulty、tags
  • 发布者信息:包含组织名称、Logo、站点 URL
  • 搜索支持:WebSite Schema 内置 SearchAction
  • 面包屑增强:完整的三级路径

🔧 配置调整 ​

配置项说明
theme/index.ts样式导入从单文件改为多模块导入,按优先级排序
style.css删除原样式文件,拆分为模块化文件
config.mtstransformHead 集成 JSON-LD 结构化数据(WebSite + TechArticle + BreadcrumbList)
styles/critical.css新增 Critical CSS 聚合入口(5 个关键样式模块 @import)
scripts/inject-critical-css.mjs新增构建后处理脚本,自动内联关键 CSS 到 98 个页面
package.jsonbuild 脚本集成注入步骤,版本升级 1.0.0 → 1.5.0
92 个 .md 文件批量补充 frontmatter:author、date、updated、difficulty 字段

| theme/components/LearningChecklist.vue | 新增学习检查清单组件(分组、进度追踪、localStorage 持久化) | | theme/index.ts | 异步导入并注册 LearningChecklist 全局组件 | | README.md | 更新项目说明:补充学习检查清单特性、组件数 22→23 | | guide/what-is-vitepress.md | 添加入门概念检查清单(5 项) | | guide/installation.md | 添加安装环境检查清单(9 项) | | basics/markdown.md | 添加 Markdown 语法检查清单(13 项) | | advanced/components.md | 添加组件开发检查清单(12 项) |

路由分割样式 ​

按路由分割样式加载(Route-based CSS Splitting) ​

将 16 个 CSS 文件从全部同步加载改为根据页面路径按需动态加载:

Bundle大小加载时机包含样式适用页面
A: Global Core~2.5KB始终同步variables.css所有页面
B: Base UI~19KB非首页动态buttons, navigation, typography, responsive, utilities文档/特殊页
C: Content~5KB文档内容页动态code, tables, custom-blocks, tocguide/basics/theme/advanced/bp
D: Home~8.7KB仅首页动态home.css首页 /
E: Special Pages~16.6KB特殊页动态components, pagesvideos/tags/changelog 等
F: Enhancement~6KB空闲时延迟animations, accessibility, print所有页面

优化效果:

场景优化前优化后减少
首页首屏~58KB (16文件)~2.5KB + 8.7KB + 内联9.9KB~63%
文档内容页~58KB (16文件)~2.5KB + 19KB + 5KB + 内联9.9KB~47%
特殊页面~58KB (16文件)~2.5KB + 19KB + 16.6KB + 内联9.9KB~26%

新增/修改文件:

文件操作说明
theme/composables/useRouteStyles.ts新增路由分割样式 composable (~170 行)
theme/index.ts修改移除静态导入,改为仅同步 variables + 调用 useRouteStyles

2026年04月01日 ​

📚 新增文档 ​

根据内容覆盖分析和与 VitePress 官方文档对比,补充了以下文档:

教程说明
路由重写 /guide/rewritesURL 重写、路径映射、多语言路由配置
Meta 与 SEO 配置 /basics/meta-seoOpen Graph、Twitter Card、结构化数据
图片优化指南 /best-practices/image-optimization压缩、懒加载、WebP、响应式图片
开源项目文档站 /examples/open-source-docsGitHub 集成、版本管理、贡献指南
SSR 兼容性 /guide/ssr-compatibilitySSR 常见问题、解决方案、最佳实践
MPA 模式 /guide/mpa-mode多页面应用模式配置、适用场景、迁移指南
llms.txt 支持 /guide/llms-txtAI 搜索优化、结构化文档索引生成
Carbon Ads 集成 /advanced/carbon-ads广告变现集成、配置方式、样式定制

📝 内容更新 ​

Badge 组件文档扩展 ​

扩展了 /advanced/components 中 Badge 组件的文档:

  • 导航栏中使用徽章的配置方法
  • 徽章类型详细说明表格
  • CSS 变量自定义颜色样式

Team Page 配置新增 ​

在 /team 页面新增 VitePress 官方 Team Components 使用指南:

  • Team Members 数据结构定义
  • VPTeamMembers 组件使用
  • VPTeamPage 完整布局示例
  • 自定义样式配置

为所有文章添加标签 ​

为项目中 83 篇文章添加了合适的标签,方便读者按标签浏览内容。

目录文件数标签示例
guide/7入门、安装、迁移、SSG
basics/10配置、Markdown、路由、导航栏
advanced/18部署、国际化、搜索、插件
theme/15主题、CSS、布局、Vue
best-practices/12SEO、性能、测试、CI/CD
examples/9实战案例、博客、作品集
根目录12学习路径、资源、案例

Tags 页面更新 ​

更新项说明
标签云更新标签数量统计,调整大小显示
详细分类从 11 个扩展到 15 个分类
其他标签新增 30+ 个细分标签展示区
统计数据文章数量更新为 83,标签分类更新为 60+

🐛 问题修复 ​

代码块嵌套问题修复 ​

修复了代码示例中代码块嵌套导致的 Markdown 解析错误。

文件修复数量
basics/custom-containers.md5 处
contributing.md1 处
best-practices/faq.md1 处

修复方法:将 ```markdown 改为 ````markdown(4个反引号),确保内部包含 3 个反引号的代码能正确嵌套显示。

表格格式问题修复 ​

修复了表格使用 || 开头导致的格式错误,涉及 9 个文件,共 101 处。

文件修复数量
theme/layout-slots.md29 处
best-practices/plugins.md14 处
theme/default-theme.md13 处
theme/testing.md11 处
theme/blog-theme-tutorial.md8 处
theme/vue-components.md7 处
theme/performance.md7 处
theme/css-variables.md6 处
theme/community-themes.md6 处

修复方法:将 || 开头的表格行改为 | 开头,符合 VitePress Markdown 表格规范。

🔧 配置调整 ​

配置项说明
data-loading.md修复重复的 frontmatter 内容

2026年03月31日 ​

✨ 新增功能 ​

新增主题开发进阶系列教程 ​

教程说明
Vue 组件开发指南 /theme/vue-componentsVue 3 组件开发、组件注册方式、组件通信、响应式数据、最佳实践
主题架构原理 /theme/architectureVitePress 主题系统架构、核心概念、生命周期钩子、构建流程详解
主题开发实战 /theme/blog-theme-tutorial从零开发博客主题完整教程,包含项目规划、核心组件开发、部署
主题打包与发布 /theme/theme-publishing项目结构、打包配置、npm 发布流程、版本管理、自动化发布
主题性能优化 /theme/performance加载优化、渲染优化、构建优化、Core Web Vitals
主题测试指南 /theme/testing单元测试、组件测试、E2E 测试、CI 集成、覆盖率统计
主题开发常见问题 /theme/theme-faq25+ 常见问题解答,涵盖配置、样式、组件、构建、SEO、部署等
主题开发工具 /theme/dev-toolsVS Code 扩展、开发工具、调试技巧、实用脚本

新增教程 ​

教程说明
TypeScript 深度集成指南 /advanced/typescript-guide类型声明、类型安全组件、数据加载类型、构建时类型检查等
Headless CMS 集成 /advanced/cms-integrationStrapi、Notion、Contentful 三种 CMS 集成方案,含 CI/CD 自动同步
评论系统集成 /advanced/comments-integrationGiscus、Waline、Twikoo 详细对比与集成指南,含迁移教程
国际化实战案例 /advanced/i18n-practice完整的中英文多语言站点搭建,含翻译管理和自动翻译工具
更多部署平台 /advanced/deployment-platformsRailway、Render、Zeabur、Fly.io 等新兴平台部署教程
站点测试指南 /best-practices/testingVitest 单元测试、Playwright E2E 测试、快照测试、可访问性测试
自定义容器语法 /basics/custom-containers提示框、警告框、代码组、自定义容器样式等完整教程
社区主题使用指南 /theme/community-themes社区主题推荐、安装配置、主题开发指南

新增实战案例 ​

案例说明
个人作品集搭建 /examples/portfolio第 8 个实战案例,涵盖首页设计、项目展示、技能矩阵、经历时间线、联系方式
电商文档站搭建 /examples/ecommerce-docs第 7 个实战案例,涵盖商品文档、API 文档、帮助中心、开发者指南

📝 内容更新 ​

更新项说明
版本标记完善主题开发相关文档全部添加版本说明和支持环境信息
布局插槽文档所有插槽表格添加版本要求列(v0.22.0+)
插件扩展文档插件表格添加 VitePress 版本和 Node.js 版本要求
案例展示扩充新增 VueUse、Pinia、Nuxt、Vitest、UnoCSS、Vue Router、Vue Macros 等 10+ 个社区案例
案例展示扩充新增 Arco Design、NutUI、Varlet 等 4 个组件库案例
案例展示扩充新增博客、作品集、简历等个人站点案例分类
示例仓库链接修复examples/index.md 占位符链接替换为实际仓库地址
视频教程时间戳videos.md 全部 6 个视频添加章节时间戳导航
学习资源扩充resources.md 插件列表从 4 个扩展至 15+ 个,新增部署平台推荐

🔧 配置调整 ​

配置项说明
侧边栏重构主题定制模块拆分为三个分组:「主题定制」「主题开发进阶」「优化与测试」
侧边栏更新主题开发进阶新增 4 个入口(Vue 组件、架构原理、开发实战、打包发布)
侧边栏更新优化与测试新增 4 个入口(性能优化、测试指南、常见问题、开发工具)
侧边栏更新基础功能新增「自定义容器语法」入口(带「新」标签)
侧边栏更新高级功能新增「国际化实战案例」入口(带「新」标签)
侧边栏更新集成与扩展新增「TypeScript 集成」「CMS 集成」「评论系统」「更多部署平台」入口
侧边栏更新实战案例新增「个人作品集搭建」入口(带「新」标签)
侧边栏更新实战案例新增「电商文档站搭建」入口(带「新」标签)
侧边栏更新最佳实践新增「站点测试指南」入口(带「新」标签)
首页更新最新特性区域扩充至 7 个新特性卡片

2026年03月28日 ​

✨ 新增功能 ​

新增教程 ​

教程说明
SSG 工具对比 /guide/ssg-comparisonVitePress 与 Nuxt Content、Docusaurus、Docsify、VuePress 的详细对比分析
插件开发指南 /advanced/plugin-developmentVitePress 插件开发完整教程,涵盖 Vite 插件、Markdown 插件、构建钩子等

EdgeOne Pages 部署支持 ​

内容说明
CNB 云构建配置完整的 cnb.yml 配置示例
EdgeOne Pages 配置edgeone.json 配置文件示例
边缘函数示例自定义重定向规则
部署优势对比EdgeOne Pages 与其他平台的对比

📝 内容更新 ​

更新项说明
部署教程增强deployment.md 新增腾讯云 EdgeOne Pages 部署章节
学习路径更新入门阶段添加 SSG 工具对比教程,高级阶段添加插件开发教程
学习时间调整总学习时长更新为 20 小时

🔧 配置调整 ​

配置项说明
侧边栏更新入门指南添加「SSG 工具对比」入口
侧边栏更新高级功能添加「插件开发」入口(带「新」标签)

2026年03月27日 ​

🚀 功能优化 ​

导航栏优化 ​

优化项说明
移除 English 入口导航栏移除外部英文链接,聚焦中文文档
移除版本切换器移除 VersionSwitcher 组件及相关配置,简化导航

域名统一管理 ​

优化项说明
SITE_URL 集中配置所有域名统一在 config.mts 的 SITE_URL 常量管理
REPO_URL 集中配置仓库链接统一在 config.mts 的 REPO_URL 常量管理
组件动态读取StructuredData、LinksLayout、GlobalFooter、Contribution 从配置读取域名

SEO 优化 ​

优化项说明
Canonical URL通过 transformHead 为每个页面动态生成 canonical 链接
结构化数据域名StructuredData 中所有 URL 从占位域名替换为实际域名
robots.txtSitemap URL 同步为实际域名

组件加载优化 ​

优化项说明
异步组件17 个非首屏组件改为 defineAsyncComponent 异步加载
首屏关键组件仅 8 个首屏关键组件保持同步加载

🗑️ 移除功能 ​

移除项说明
RSS 订阅配置移除不存在的 /rss.xml 引用,避免 404
VersionSwitcher 组件组件及配置已清理
Contribution 错误链接"参与贡献"链接从上游 vuejs/vitepress 修正为本项目仓库

🔧 配置调整 ​

配置项说明
themeConfig.siteUrl新增站点域名配置字段,类型声明已补充
env.d.ts 类型扩展新增 siteUrl 类型声明
socialLinks / editLink改为引用 REPO_URL 常量

🔧 工程优化 ​

robots.txt 修复 ​

优化项说明
移除 JS/JSON 爬取限制删除 Disallow: /*.js$ 和 Disallow: /*.json$,修复搜索引擎无法正常渲染 SPA 页面的问题

样式文件拆分 ​

优化项说明
style.css 拆分主文件从 2255 行缩减至 1036 行(减少 54%),拆分为 4 个职责明确的 CSS 文件
styles/components.css组件全局样式(离线提示、复制提示、快捷键面板、阅读进度等),171 行
styles/home.css首页专属样式(统计卡片、快速导航、版本徽章等),492 行
styles/pages.css页面级样式(视频页、标签页、团队页、案例页、404 页等),477 行
合并重复打印样式原文件中两处 @media print 块合并为一处完整版本
合并重复变量定义原文件中 3 处 :root 变量块合并为 1 处

2026年03月26日 ​

✨ 新增功能 ​

新增组件 ​

组件说明
HomeEnhance首页动态化增强,Hero 名称渐变流光、标语轮播、图片浮动动画、按钮入场动画
KnowledgeGraph知识图谱可视化组件,交互式节点图展示 VitePress 知识体系
PageTransition页面切换过渡动画,CSS class 驱动的淡入淡出效果
ScrollReveal滚动揭示动画,基于 IntersectionObserver 的元素入场效果
VersionSwitcher版本切换器,导航栏中的 VitePress 版本快速切换

新增页面 ​

页面说明
企业官网搭建 /examples/corporate-site第 6 个实战案例,涵盖专业首页 Hero、产品展示、联系表单、SEO 结构化数据
功能说明
快速链接区域四分类快速链接(学习指南、实战案例、最佳实践、社区)
RSS 订阅页脚 RSS 订阅入口
返回顶部平滑滚动返回顶部按钮
社交媒体链接GitHub、B站等社交平台入口

ReadingProgress 增强 ​

功能说明
阅读历史记录最近 15 条阅读历史,支持标题映射显示
历史面板点击即可查看和跳转历史页面

🚀 功能优化 ​

导航与侧边栏 ​

优化项说明
侧边栏折叠入门指南、基础功能、主题定制、高级功能、实战案例分组默认折叠
导航扩展新增"更多"菜单,包含标签分类、文章归档、贡献者、更新日志入口
版本切换器导航栏集成 VitePress 版本切换功能
导航精简资源中心菜单从 9 项精简至 5 项

视频教程优化 ​

优化项说明
内嵌播放视频从外链卡片改为 iframe 内嵌播放器,支持 B站和 YouTube
用户体验无需跳转即可直接观看教程视频

代码示例优化 ​

优化项说明
StackBlitz 集成内嵌 StackBlitz 在线编辑器,无需本地安装即可体验 VitePress
快速模板新增最小化模板和完整模板,一键复制即可使用

📝 内容更新 ​

更新项说明
首页统计实战案例数量更新 5 → 6,添加版本追踪区域和 scroll-reveal 动画
学习路径QuizComponent 改用 script setup 变量引用,修复构建错误;新增知识图谱和 mermaid 流程图
错误处理新增"常见踩坑指南"章节(base 配置、cleanUrls、CSS 优先级、VuePress 迁移、性能优化等)
FAQ 扩充新增 PWA 相关(Service Worker、缓存策略)、多语言问题、VuePress 迁移、Markdown 高级问题等
贡献指南新增"贡献者荣誉"体系(6 个等级、认可方式、季度贡献之星)和"贡献统计"章节
API 文档api-config.md 和 api-runtime.md 新增快速导航目录
案例索引examples/index.md 新增企业官网示例入口

🎨 样式优化 ​

样式类说明
Hero 动画名称渐变流光、图片浮动、按钮交错入场动画
Features 动画卡片交错入场效果
滚动揭示.scroll-reveal 类,元素进入视口时淡入上滑
页面过渡淡入淡出页面切换效果
页脚样式多列链接布局、分隔线、返回顶部按钮样式
阅读历史弹出面板、列表项、时间戳样式
版本切换器导航栏下拉选择器样式
知识图谱SVG 节点图、交互高亮、连线和标签样式
视频嵌入iframe 嵌入容器响应式适配
演练场StackBlitz 编辑器嵌入容器样式

🐛 问题修复 ​

修复项说明
QuizComponent 构建修复多行内联属性导致 VitePress markdown-to-SFC 编译失败,改用 script setup 变量引用
学习路径重复删除阶段三重复的教程列表和测试内容
双重页脚移除冗余的 DocFooter 组件

🔧 配置调整 ​

配置项说明
全局组件注册新增 KnowledgeGraph 组件全局注册
插槽配置新增 nav-bar-content-before 和 nav-screen-content-before 插槽

2026年03月14日 ​

✨ 新增功能 ​

用户体验组件 ​

组件说明
ReadingProgress学习进度追踪,使用 localStorage 记录已读页面
RelatedPosts相关文章推荐,基于标签匹配推荐相关内容
KeyboardShortcuts键盘快捷键支持(? 显示帮助,Ctrl+K 搜索)
OfflineIndicator离线提示条,断网时自动显示
CopyToast代码复制成功 Toast 提示
QuizComponent学习测验组件,支持多题目和答案解析

新增页面 ​

页面说明
视频教程 /videosB站/YouTube 视频资源汇总页面
案例展示 /showcase展示优秀 VitePress 站点案例
代码示例 /playground在线体验 VitePress 功能

🔧 配置调整 ​

PWA 完整配置 ​

配置项说明
manifest应用名称、图标、主题色完整配置
workbox缓存策略、自动更新、Service Worker 配置
离线支持支持离线浏览文档内容

构建优化 ​

优化项说明
chunkSizeWarningLimit提高到 1000KB,减少警告
类型声明添加 env.d.ts Vue 组件类型声明

🚀 功能优化 ​

  • 导航增强:资源中心菜单添加"视频教程"入口,带"新"标识
  • 首页优化:快速导航扩展为 6 项,新增视频教程和代码示例入口
  • 学习路径:添加阶段测试 Quiz 组件,增强互动学习体验
  • 主题集成:所有新组件已集成到主题布局中
  • 页脚统一:整合页脚与备案信息为统一 GlobalFooter 组件

🎨 样式优化 ​

样式类说明
离线提示条固定顶部显示,橙色背景
复制 Toast右下角弹出动画效果
移动端导航底部固定导航栏(已移除,使用默认导航)
快捷键面板居中弹窗样式
学习进度侧边栏底部进度显示
动画效果淡入、滑入、缩放动画类

🐛 问题修复 ​

  • 修复 index.ts 语法错误(括号不匹配)
  • 修复 ReadingProgress.vue SSR 兼容问题
  • 修复 OfflineIndicator.vue SSR 兼容问题
  • 修复 PWA 配置调用方式错误
  • 移除无效的 manualChunks 配置

2026年03月13日 ​

✨ 新增功能 ​

PWA 支持 ​

功能说明
离线访问支持 PWA 离线浏览文档
安装提示提供网站安装到桌面的引导
自动更新Service Worker 自动更新机制

代码示例仓库 ​

内容说明
示例仓库入口/examples/ 提供所有示例项目的代码仓库链接
克隆与下载提供 GitHub 克隆和 ZIP 下载方式
贡献指南示例代码的贡献和改进流程

进阶挑战题 ​

为 5 个实战案例添加了进阶挑战任务:

案例挑战数量难度范围
博客搭建6 个挑战⭐⭐ ~ ⭐⭐⭐⭐
组件库文档6 个挑战⭐⭐⭐ ~ ⭐⭐⭐⭐
API 文档站6 个挑战⭐⭐ ~ ⭐⭐⭐⭐⭐
个人简历站6 个挑战⭐⭐⭐ ~ ⭐⭐⭐⭐
知识库站点6 个挑战⭐⭐⭐ ~ ⭐⭐⭐⭐⭐

📝 内容更新 ​

  • 首页统计更新:核心教程 30+ → 37+,学习时长 20h → 25h+
  • 学习路径更新:添加代码示例仓库和 PWA 支持教程入口
  • 侧边栏优化:新增代码示例入口,新增 PWA 支持菜单项

🔧 配置调整 ​

  • 添加 @vite-pwa/vitepress 依赖
  • 配置 PWA manifest 和 Service Worker
  • 添加 PWA 相关的 meta 标签

2026年02月28日 ​

✨ 新增功能 ​

新增布局组件 ​

布局说明
BlogListLayout博客文章列表布局,支持标签筛选和搜索
AboutLayout关于页面布局,支持个人信息、技能、经历展示
LinksLayout友情链接布局,支持分类展示和申请说明
ProjectsLayout项目展示布局,支持精选项目和状态筛选

使用方式:在 frontmatter 中设置 layout: blog-list、layout: about、layout: links、layout: projects 即可调用。

新增组件 ​

组件说明
LikeButton文章点赞功能,支持飘心动画效果
ImageZoom图片点击缩放灯箱效果
Contribution贡献者展示组件

新增页面 ​

页面说明
标签分类 /tags按标签浏览文章,支持标签云展示
文章归档 /archive按时间线浏览文章列表
贡献者 /contributors展示项目贡献者和参与情况

新增教程 ​

教程说明
自定义布局 /theme/custom-layouts布局组件使用教程和配置说明
VitePress 新特性介绍 VitePress 2.0/3.0 的新功能和改进
Algolia 搜索集成完整的 Algolia DocSearch 集成教程
组件库文档实战扩充完整的组件库文档搭建教程

🚀 功能优化 ​

  • 首页增强:新增快速导航、最新特性、用户反馈三个功能区域
  • 导航优化:添加标签分类、文章归档、贡献者导航入口
  • 侧边栏优化:添加新特性、Algolia 搜索等入口
  • 分享按钮优化:ShareButton 组件独立运行,不再依赖 ReadingTime 组件

🎨 样式优化 ​

  • 链接样式:首页所有链接取消下划线,提升视觉体验
  • SSR 兼容:修复组件在服务端渲染时的 localStorage 错误
  • 页脚优化:添加公安网安备案信息,符合国内网站合规要求

🐛 问题修复 ​

  • 修复 Markdown 中嵌套 Vue 模板语法的构建错误
  • 修复 localStorage 在 SSR 构建时的访问错误

2026年02月27日 ​

✨ 新增功能 ​

  • SEO 优化指南:完整的搜索引擎优化教程
  • CI/CD 自动化部署:GitHub Actions、Vercel、Netlify 等部署方案

🚀 功能优化 ​

  • 导航菜单简化:移除 SVG 图标,采用纯文字导航,参考默认主题风格
  • 激活状态优化:导航激活状态增加底部下划线指示器

🎨 样式优化 ​

  • 配色方案重构:参考 VitePress 默认主题的 3 级色阶系统,完善明亮/深色模式配色
  • 深色模式品牌色调整:#a5b4fc 作为深色模式主色,确保对比度
  • 按钮配色更新:使用 CSS 变量引用,便于统一管理

🐛 问题修复 ​

  • 修复深色模式下品牌色对比度不足的问题
  • 修复导航悬停效果不一致的问题

2026年02月15日 ​

✨ 新增功能 ​

  • 自定义 404 页面,提供更好的用户体验和推荐导航
  • 面包屑导航组件,方便用户了解当前位置
  • 阅读时间统计组件,预估文章阅读时长
  • 返回顶部按钮,优化长页面浏览体验
  • 结构化数据支持,提升搜索引擎优化

🚀 功能优化 ​

  • 优化深色模式样式适配,统一品牌色彩
  • 改进首页统计区域展示效果
  • 优化导航栏图标系统,支持 SVG 图标
  • 完善移动端响应式布局

📝 内容更新 ​

  • 完善团队介绍页面内容
  • 更新学习路径中的工具推荐
  • 扩充学习资源页面

🐛 问题修复 ​

  • 修复部分页面在深色模式下的样式问题
  • 修复导航栏激活状态显示不一致的问题

2026年01月01日 ​

首次发布 ​

本项目正式上线,提供以下核心内容:

入门指南 ​

教程说明
什么是 VitePressVitePress 简介和核心特点
安装与环境配置开发环境搭建指南
项目结构解析目录结构和文件说明
创建第一个页面快速上手实践
从 VuePress 迁移迁移指南和注意事项

基础功能 ​

教程说明
Markdown 扩展语法VitePress 增强的 Markdown 功能
Frontmatter 配置页面级配置说明
配置文件详解完整的配置选项说明
导航栏配置自定义导航栏
侧边栏配置多级侧边栏设置
静态资源管理图片、样式等资源处理
路由详解文件路由机制

主题定制 ​

教程说明
默认主题配置使用和配置默认主题
自定义主题开发个性化主题
CSS 变量覆盖样式定制方法
布局插槽扩展布局功能
菜单图标配置导航图标设置

高级功能 ​

教程说明
组件使用在 Markdown 中使用 Vue 组件
数据加载动态数据获取和处理
多语言支持国际化配置
搜索功能本地搜索和第三方搜索
构建优化构建性能优化
部署与发布多平台部署指南
站点统计访问统计和分析
RSS 与站点地图SEO 增强

实战案例 ​

案例说明
博客搭建个人技术博客搭建
组件库文档组件文档站开发
API 文档站REST API 文档
个人简历站在线简历网站
知识库站点团队知识库搭建

最佳实践 ​

教程说明
性能优化网站性能优化建议
常见问题FAQ 汇总
插件扩展常用插件推荐
速查表常用配置速查

开发计划 ​

近期计划 ​

功能状态预计时间
视频教程内容✅ 已完成2026年3月
更多实战案例🚧 进行中2026年3月
英文版文档📋 规划中2026年4月
互动式测验系统✅ 已完成2026年3月
键盘快捷键支持✅ 已完成2026年3月

长期规划 ​

功能描述状态
互动式教程系统在线代码编辑和运行💡 构思中
在线代码演练场实时代码演示环境✅ 已完成
社区贡献者展示展示项目贡献者✅ 已完成
版本切换功能支持多版本文档❌ 已移除
标签分类系统按标签浏览文章✅ 已完成
文章归档页面按时间线展示文章✅ 已完成
PWA 离线支持支持离线访问文档✅ 已完成
进阶挑战题实战案例进阶练习✅ 已完成
学习进度追踪记录用户学习进度✅ 已完成
相关文章推荐基于标签推荐相关文章✅ 已完成
案例展示页面优秀站点案例展示✅ 已完成
移动端优化响应式导航适配✅ 已完成

贡献指南 ​

如果你发现文档有误或希望补充内容,欢迎通过以下方式参与:

  1. 提交 Issue - 报告问题或提出建议
  2. Pull Request - 直接参与代码贡献
  3. 讨论交流 - 在 GitHub Discussions 分享想法

变更类型说明

本更新日志使用以下 Emoji 标记标识不同类型的变更:

标记类型说明
✨新增功能全新功能或重要特性
🚀功能优化现有功能的改进和优化
📝内容更新文档内容的补充和完善
🎨样式优化UI/UX 和视觉效果的改进
🐛问题修复Bug 修复和问题解决
🔧配置调整配置文件或构建相关调整
⚠️弃用提醒即将移除或变更的功能
💥破坏性变更需要用户注意的不兼容变更

保持更新

本教程会持续更新,建议 Star 项目以获取最新动态!

贡献者

加载中...

想要成为贡献者?

在 CNB 上参与贡献