用途:把已生成的 wiki Markdown 页面转换为可浏览的 VitePress 静态站点,输出暗色主题、支持 Mermaid 图表交互。触发场景包括用户要求“build a site”“package as VitePress”,或运行 /deep-wiki:build 命令,以及需要从 wiki 页面得到可浏览 HTML 输出时。
主要能力:在 wiki-site/ 目录生成 VitePress 脚手架,包含 .vitepress/config.mts、.vitepress/theme/index.ts、.vitepress/theme/custom.css、public/、生成的 .md 页面、package.json 与 index.md。配置使用 vitepress-plugin-mermaid 的 withMermaid 包装,appearance 设为 'dark',并根据目录结构配置 themeConfig.nav 与 themeConfig.sidebar。Mermaid 暗色主题通过三层修复实现:config.mts 中的 themeVariables、custom.css 中的 CSS 覆盖(带 !important)、以及 theme/index.ts 中用 onMounted 加轮询替换内联样式。还提供 Mermaid 图表点击放大:将 .mermaid 容器包裹为可点击元素,点击后打开全屏模态框。
使用方式:构建前先扫描所有 .md 文件做后处理,包括把 <br/> 替换为 <br>、在代码围栏外将裸 <T> 泛型参数用反引号包裹、确保每页有含 title 与 description 的 YAML frontmatter。随后执行 cd wiki-site && npm install && npm run docs:build,输出位于 wiki-site/.vitepress/dist/。
限制与注意事项:Mermaid 异步渲染,onMounted 触发时 SVG 尚不存在,必须轮询;不要使用 isCustomElement 处理裸 <T>,会导致更严重崩溃;Mermaid 节点文本使用内联样式且优先级最高,仅靠 CSS 无法修复;enhanceApp() 在 SSR 期间运行,此时 document 不存在,只能用 setup()。该技能仅适用于上述明确范围,输出不能替代环境相关的验证、测试或专家审查;若缺少必要输入、权限、安全边界或成功标准,应停止并请求澄清。