wiki-vitepress

Wiki VitePress 打包器

将生成的 Wiki Markdown 文件转换为精美的 VitePress 静态站点，采用深色主题并支持交互式 Mermaid 图表。

适用场景

• 用户要求“构建站点”或“打包为 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 深色模式：三层修复方案

第 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.ts）

适当的作者级 !important 规则可以覆盖普通内联样式。优先使用渲染器主题配置和作用域 CSS；避免重写每个 SVG 的填充色和描边色，因为这会破坏语义颜色。如果确实需要针对特定版本的 DOM 变通方案，请使用范围明确的挂载钩子，并在卸载和路由切换时清理定时器和监听器：

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()——SSR 期间 DOM 不存在。

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.appendChild(el.cloneNode(true))
    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); }

模态框示意代码并不完整：生产级 UI 需要提供具有无障碍支持的按钮和对话框名称、Escape 键处理、焦点限制与恢复，以及监听器清理。请将 Markdown 和图表内容视为不可信内容；保持严格的 Mermaid 安全设置，不要为了方便渲染而启用任意 HTML/脚本执行。

后处理规则

运行 VitePress 构建前，扫描所有 .md 文件并修复以下问题：

• 保留有效的自闭合 <br/>/<br> 标记，除非实际编译错误要求进行范围明确的修复；不要重写代码围栏中的文本
• 在代码围栏外，将裸露的 <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() 会在 document 不存在的 SSR 期间运行——只能使用 setup()

适用场景

当需要执行概述中所述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审核的替代品。
• 如果缺少必要输入、权限、安全边界或成功标准，请停止并要求澄清。