---

name: wiki-vitepress description: "将生成的wiki Markdown文件转换为带有暗色主题和交互式Mermaid图表的精美VitePress静态站点。当用户要求'构建站点'或'打包为VitePress'、用户运行/deep-wiki、或用户想要从生成的wiki页面获得可浏览的HTML输出时使用。" risk: unknown source: community date_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.sidebar
• Mermaid配置必须设置暗色主题变量：

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：三层修复

第一层：主题变量（在config.mts中）

通过 mermaid.themeVariables 设置，如上所示。

第二层：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; }

第三层：内联样式替换（theme/index.ts）

Mermaid内联 style 属性会覆盖一切。使用 onMounted + 轮询来替换它们：

import { onMounted } from 'vue'

// In setup()
onMounted(() => {
  let attempts = 0
  const fix = setInterval(() => {
    document.querySelectorAll('.mermaid svg [style]').forEach(el => {
      const s = (el as HTMLElement).style
      if (s.fill && !s.fill.includes('#1e3a5f')) s.fill = '#1e3a5f'
      if (s.stroke && !s.stroke.includes('#4a9eed')) s.stroke = '#4a9eed'
      if (s.color) s.color = '#e0e0e0'
    })
    if (++attempts >= 20) clearInterval(fix)
  }, 500)
})

使用 setup() 配合 onMounted，不要使用 enhanceApp() —— DOM在SSR期间不存在。

Mermaid图表点击缩放

将每个 .mermaid 容器包装在可点击的包装器中，打开全屏模态框：

document.querySelectorAll('.mermaid').forEach(el => {
  el.style.cursor = 'zoom-in'
  el.addEventListener('click', () => {
    const modal = document.createElement('div')
    modal.className = 'mermaid-zoom-modal'
    modal.innerHTML = el.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/> 替换为 <br>（Vue模板编译器兼容性）
• 将代码围栏外的裸 <T> 泛型参数用反引号包裹
• 确保每个页面都有包含 title 和 description 的YAML frontmatter

构建

cd wiki-site && npm install && npm run docs:build

输出到 wiki-site/.vitepress/dist/。

已知陷阱

• Mermaid异步渲染 —— onMounted 触发时SVG尚不存在。必须轮询。
• 裸 <T> 的 isCustomElement 编译器选项会导致更严重的崩溃 —— 不要使用
• Mermaid中的节点文本使用具有最高优先级的内联 style —— 仅CSS无法修复
• enhanceApp() 在SSR期间运行，此时 document 不存在 —— 仅使用 setup()

何时使用

此技能适用于执行概述中描述的工作流程或操作。

限制

• 仅在任务明确匹配上述描述的范围时使用此技能。
• 不要将输出视为特定环境验证、测试或专家审查的替代品。
• 如果缺少所需的输入、权限、安全边界或成功标准，请停下来要求澄清。