Back to Details

wiki-vitepress

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Wiki VitePress Packager

Wiki VitePress 打包工具

Transform generated wiki Markdown files into a polished VitePress static site with dark theme and interactive Mermaid diagrams.
将生成的维基Markdown文件转换为带有深色主题和交互式Mermaid图表的精致VitePress静态站点。

When to Activate

激活场景

  • User asks to "build a site" or "package as VitePress"
  • User runs the 
    /deep-wiki:build
    command
  • User wants a browsable HTML output from generated wiki pages
  • 用户要求“构建网站”或“打包为VitePress”
  • 用户运行
    /deep-wiki:build
    命令
  • 用户希望从生成的维基页面得到可浏览的HTML输出

VitePress Scaffolding

VitePress 脚手架结构

Generate the following structure in a 
wiki-site/
directory:
wiki-site/
├── .vitepress/
│   ├── config.mts
│   └── theme/
│       ├── index.ts
│       └── custom.css
├── public/
├── [generated .md pages]
├── package.json
└── index.md
在
wiki-site/
目录中生成以下结构：
wiki-site/
├── .vitepress/
│   ├── config.mts
│   └── theme/
│       ├── index.ts
│       └── custom.css
├── public/
├── [生成的.md页面]
├── package.json
└── index.md

Config Requirements (
config.mts
)

配置要求 (
config.mts
)

  • Use 
    withMermaid
    wrapper from 
    vitepress-plugin-mermaid
  • Set 
    appearance: 'dark'
    for dark-only theme
  • Configure 
    themeConfig.nav
    and 
    themeConfig.sidebar
    from the catalogue structure
  • Mermaid config must set dark theme variables:
typescript
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'
  }
}
  • 使用
    vitepress-plugin-mermaid
    中的
    withMermaid
    包装器
  • 设置
    appearance: 'dark'
    以启用纯深色主题
  • 根据目录结构配置
    themeConfig.nav
    和
    themeConfig.sidebar
  • Mermaid配置必须设置深色主题变量：
typescript
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'
  }
}

Dark-Mode Mermaid: Three-Layer Fix

深色模式Mermaid：三层修复方案

Layer 1: Theme Variables (in config.mts)

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

Set via 
mermaid.themeVariables
as shown above.
通过上述
mermaid.themeVariables
进行设置。

Layer 2: CSS Overrides (
custom.css
)

第二层：CSS覆盖 (
custom.css
)

Target Mermaid SVG elements with 
!important
:
css
.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; }
使用
!important
定位Mermaid SVG元素：
css
.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; }

Layer 3: Inline Style Replacement (
theme/index.ts
)

第三层：内联样式替换 (
theme/index.ts
)

Mermaid inline 
style
attributes override everything. Use 
onMounted
+ polling to replace them:
typescript
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)
})
Use 
setup()
with 
onMounted
, NOT 
enhanceApp()
— DOM doesn't exist during SSR.
Mermaid的内联
style
属性会覆盖所有样式。使用
onMounted
+ 轮询来替换这些样式：
typescript
import { onMounted } from 'vue'

// 在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不存在。

Click-to-Zoom for Mermaid Diagrams

Mermaid图表的点击缩放功能

Wrap each 
.mermaid
container in a clickable wrapper that opens a fullscreen modal:
typescript
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)
  })
})
Modal CSS:
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); }
将每个
.mermaid
容器包裹在可点击的容器中，点击后打开全屏模态框：
typescript
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：
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); }

Post-Processing Rules

后处理规则

Before VitePress build, scan all 
.md
files and fix:
  • Replace 
    <br/>
    with 
    <br>
    (Vue template compiler compatibility)
  • Wrap bare 
    <T>
    generic parameters in backticks outside code fences
  • Ensure every page has YAML frontmatter with 
    title
    and 
    description
在VitePress构建前，扫描所有
.md
文件并修复以下问题：
  • 将
    <br/>
    替换为
    <br>
    （兼容Vue模板编译器）
  • 在代码块外的裸
    <T>
    泛型参数前后添加反引号
  • 确保每个页面都包含带有
    title
    和
    description
    的YAML前置元数据

Build

构建步骤

bash
cd wiki-site && npm install && npm run docs:build
Output goes to 
wiki-site/.vitepress/dist/
.
bash
cd wiki-site && npm install && npm run docs:build
构建产物输出到
wiki-site/.vitepress/dist/
目录。

Known Gotchas

已知问题

  • Mermaid renders async — SVGs don't exist when 
    onMounted
    fires. Must poll.
  • isCustomElement
    compiler option for bare 
    <T>
    causes worse crashes — do NOT use it
  • Node text in Mermaid uses inline 
    style
    with highest specificity — CSS alone won't fix it
  • enhanceApp()
    runs during SSR where 
    document
    doesn't exist — use 
    setup()
    only
  • Mermaid是异步渲染的——
    onMounted
    触发时SVG还不存在，必须使用轮询。
  • 为裸
    <T>
    设置
    isCustomElement
    编译器选项会导致更严重的崩溃——请勿使用。
  • Mermaid中的节点文本使用具有最高优先级的内联
    style
    ——仅靠CSS无法修复。
  • enhanceApp()
    在SSR期间运行，此时
    document
    不存在——仅使用
    setup()
    。