Wiki Vitepress

1---
2name: wiki-vitepress
3description: Packages generated wiki Markdown into a VitePress static site with dark theme, dark-mode Mermaid diagrams with click-to-zoom, and production build output. Use when the user wants to create a browsable website from generated wiki pages.
4---
5 
6# Wiki VitePress Packager
7 
8Transform generated wiki Markdown files into a polished VitePress static site with dark theme and interactive Mermaid diagrams.
9 
10## When to Activate
11 
12- User asks to "build a site" or "package as VitePress"
13- User runs the `/deep-wiki:build` command
14- User wants a browsable HTML output from generated wiki pages
15 
16## VitePress Scaffolding
17 
18Generate the following structure in a `wiki-site/` directory:
19 
20```
21wiki-site/
22├── .vitepress/
23│   ├── config.mts
24│   └── theme/
25│       ├── index.ts
26│       └── custom.css
27├── public/
28├── [generated .md pages]
29├── package.json
30└── index.md
31```
32 
33## Config Requirements (`config.mts`)
34 
35- Use `withMermaid` wrapper from `vitepress-plugin-mermaid`
36- Set `appearance: 'dark'` for dark-only theme
37- Configure `themeConfig.nav` and `themeConfig.sidebar` from the catalogue structure
38- Mermaid config must set dark theme variables:
39 
40```typescript
41mermaid: {
42  theme: 'dark',
43  themeVariables: {
44    primaryColor: '#1e3a5f',
45    primaryTextColor: '#e0e0e0',
46    primaryBorderColor: '#4a9eed',
47    lineColor: '#4a9eed',
48    secondaryColor: '#2d4a3e',
49    tertiaryColor: '#2d2d3d',
50    background: '#1a1a2e',
51    mainBkg: '#1e3a5f',
52    nodeBorder: '#4a9eed',
53    clusterBkg: '#16213e',
54    titleColor: '#e0e0e0',
55    edgeLabelBackground: '#1a1a2e'
56  }
57}
58```
59 
60## Dark-Mode Mermaid: Three-Layer Fix
61 
62### Layer 1: Theme Variables (in config.mts)
63Set via `mermaid.themeVariables` as shown above.
64 
65### Layer 2: CSS Overrides (`custom.css`)
66Target Mermaid SVG elements with `!important`:
67 
68```css
69.mermaid .node rect,
70.mermaid .node circle,
71.mermaid .node polygon { fill: #1e3a5f !important; stroke: #4a9eed !important; }
72.mermaid .edgeLabel { background-color: #1a1a2e !important; color: #e0e0e0 !important; }
73.mermaid text { fill: #e0e0e0 !important; }
74.mermaid .label { color: #e0e0e0 !important; }
75```
76 
77### Layer 3: Inline Style Replacement (`theme/index.ts`)
78Mermaid inline `style` attributes override everything. Use `onMounted` + polling to replace them:
79 
80```typescript
81import { onMounted } from 'vue'
82 
83// In setup()
84onMounted(() => {
85  let attempts = 0
86  const fix = setInterval(() => {
87    document.querySelectorAll('.mermaid svg [style]').forEach(el => {
88      const s = (el as HTMLElement).style
89      if (s.fill && !s.fill.includes('#1e3a5f')) s.fill = '#1e3a5f'
90      if (s.stroke && !s.stroke.includes('#4a9eed')) s.stroke = '#4a9eed'
91      if (s.color) s.color = '#e0e0e0'
92    })
93    if (++attempts >= 20) clearInterval(fix)
94  }, 500)
95})
96```
97 
98Use `setup()` with `onMounted`, NOT `enhanceApp()` — DOM doesn't exist during SSR.
99 
100## Click-to-Zoom for Mermaid Diagrams
101 
102Wrap each `.mermaid` container in a clickable wrapper that opens a fullscreen modal:
103 
104```typescript
105document.querySelectorAll('.mermaid').forEach(el => {
106  el.style.cursor = 'zoom-in'
107  el.addEventListener('click', () => {
108    const modal = document.createElement('div')
109    modal.className = 'mermaid-zoom-modal'
110    modal.innerHTML = el.outerHTML
111    modal.addEventListener('click', () => modal.remove())
112    document.body.appendChild(modal)
113  })
114})
115```
116 
117Modal CSS:
118```css
119.mermaid-zoom-modal {
120  position: fixed; inset: 0;
121  background: rgba(0,0,0,0.9);
122  display: flex; align-items: center; justify-content: center;
123  z-index: 9999; cursor: zoom-out;
124}
125.mermaid-zoom-modal .mermaid { transform: scale(1.5); }
126```
127 
128## Post-Processing Rules
129 
130Before VitePress build, scan all `.md` files and fix:
131- Replace `<br/>` with `<br>` (Vue template compiler compatibility)
132- Wrap bare `<T>` generic parameters in backticks outside code fences
133- Ensure every page has YAML frontmatter with `title` and `description`
134 
135## Build
136 
137```bash
138cd wiki-site && npm install && npm run docs:build
139```
140 
141Output goes to `wiki-site/.vitepress/dist/`.
142 
143## Known Gotchas
144 
145- Mermaid renders async — SVGs don't exist when `onMounted` fires. Must poll.
146- `isCustomElement` compiler option for bare `<T>` causes worse crashes — do NOT use it
147- Node text in Mermaid uses inline `style` with highest specificity — CSS alone won't fix it
148- `enhanceApp()` runs during SSR where `document` doesn't exist — use `setup()` only
149