name: wiki-vitepressdescription: “Transform generated wiki Markdown files into a polished VitePress static site with dark theme and interactive Mermaid diagrams. Use when user asks to “build a site” or “package as VitePress”, user runs the /deep-wiki, or user wants a browsable HTML output from generated wiki pages.”risk: criticalsource: communitydate_added: “2026-02-27”Wiki VitePress 打包器将生成的 Wiki Markdown 文件转化为带有深色主题和交互式 Mermaid 图表的精美 VitePress 静态站点。何时使用用户要求构建站点或打包为 VitePress用户运行/deep-wiki:build命令用户想要从生成的 Wiki 页面获得可浏览的 HTML 输出VitePress 脚手架在wiki-site/目录中生成以下结构wiki-site/ ├── .vitepress/ │ ├── config.mts │ └── theme/ │ ├── index.ts │ └── custom.css ├── public/ ├── [generated .md pages] ├── package.json └── index.md配置要求config.mts使用来自vitepress-plugin-mermaid的withMermaid包装器设置appearance: dark以使用纯深色主题根据目录结构配置themeConfig.nav和themeConfig.sidebarMermaid 配置必须设置深色主题变量mermaid:{theme:dark,themeVariables:{primaryColor:#1e3a5f,primaryTextColor:#e0e0e0,primaryBorderColor:#4a9eed,lineColor:#4a9eed,secondaryColor:#2d4a3e,tertiaryColor:#2d2d3d,background:#1a1a2e,mainBkg:#1e3a5f,nodeBorder:#4a9eed,clusterBkg:#16213e,titleColor:#e0e0e0,edgeLabelBackground:#1a1a2e}}深色模式 Mermaid三层修复第 1 层主题变量在 config.mts 中按上述方式通过mermaid.themeVariables设置。第 2 层CSS 覆盖custom.css用!important定位 Mermaid SVG 元素.mermaid .node rect, .mermaid .node circle, .mermaid .node polygon{fill:#1e3a5f!important;stroke:#4a9eed!important;}.mermaid .edgeLabel{background-color:#1a1a2e!important;color:#e0e0e0!important;}.mermaid text{fill:#e0e0e0!important;}.mermaid .label{color:#e0e0e0!important;}第 3 层内联样式替换theme/index.tsMermaid 的内联style属性会覆盖一切。使用onMounted 轮询来替换它们import{onMounted}fromvue// In setup()onMounted((){letattempts0constfixsetInterval((){document.querySelectorAll(.mermaid svg [style]).forEach(el{consts(elasHTMLElement).styleif(s.fill!s.fill.includes(#1e3a5f))s.fill#1e3a5fif(s.stroke!s.stroke.includes(#4a9eed))s.stroke#4a9eedif(s.color)s.color#e0e0e0})if(attempts20)clearInterval(fix)},500)})使用带onMounted的setup()而不要用enhanceApp()——SSR 期间 DOM 不存在。Mermaid 图表的点击放大将每个.mermaid容器包装在可点击的包装器中打开全屏模态框document.querySelectorAll(.mermaid).forEach(el{el.style.cursorzoom-inel.addEventListener(click,(){constmodaldocument.createElement(div)modal.classNamemermaid-zoom-modalmodal.innerHTMLel.outerHTML modal.addEventListener(click,()modal.remove())document.body.appendChild(modal)})})模态框 CSS.mermaid-zoom-modal{position:fixed;inset:0;background:rgba(0,0,0,0.9);display:flex;align-items:center;justify-content:center;z-index:9999;cursor:zoom-out;}.mermaid-zoom-modal .mermaid{transform:scale(1.5);}后处理规则在 VitePress 构建之前扫描所有.md文件并修复将br/替换为brVue 模板编译器兼容性在代码围栏之外将裸T泛型参数用反引号包裹确保每个页面都有带title和description的 YAML frontmatter构建cdwiki-sitenpminstallnpmrun docs:build输出位于wiki-site/.vitepress/dist/。已知陷阱Mermaid 是异步渲染的——onMounted触发时 SVG 还不存在。必须轮询。用于裸T的isCustomElement编译器选项会导致更严重的崩溃——不要使用它Mermaid 中的节点文本使用特异性最高的内联style——仅靠 CSS 无法修复enhanceApp()在 SSR 期间运行此时document不存在——只使用setup()何时使用此技能适用于执行概述中描述的工作流或操作。局限性仅当任务明确匹配上述范围时才使用此技能。不要将输出视为针对特定环境验证、测试或专家审查的替代品。如果缺少必要的输入、权限、安全边界或成功标准请停下来询问澄清。