Wiki VitePress Packager

Transform generated wiki Markdown files into a polished VitePress static site with dark theme and interactive Mermaid diagrams.

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 Scaffolding

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

Config Requirements (

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:

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

Layer 1: Theme Variables (in config.mts)

Set via

mermaid.themeVariables

as shown above.

Layer 2: CSS Overrides (

custom.css

)

Target Mermaid SVG elements with

!important

:

.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

)

Mermaid inline

style

attributes override everything. Use

onMounted

+ polling to replace them:

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.

Click-to-Zoom for Mermaid Diagrams

Wrap each

.mermaid

container in a clickable wrapper that opens a fullscreen modal:

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:

.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

Build

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

Output goes to

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