Wiki VitePress Packager

Transforma los archivos Markdown de wiki generados en un sitio web estático de VitePress con un acabado impecable, tema oscuro y diagramas Mermaid interactivos.

Cuándo activarlo

• El usuario solicita «crear un sitio» o «empaquetar como VitePress»
• El usuario ejecuta el comando /deep-wiki:build
• El usuario desea un resultado en HTML navegable a partir de las páginas wiki generadas

Estructura de VitePress

Genera la siguiente estructura en el directorio wiki-site/:

wiki-site/
├── .vitepress/
│   ├── config.mts
│   └── theme/
│       ├── index.ts
│       └── custom.css
├── public/
├── [páginas .md generadas]
├── package.json
└── index.md

Requisitos de configuración (config.mts)

• Utiliza el envoltorio withMermaid de vitepress-plugin-mermaid
• Establece appearance: 'dark' para un tema exclusivamente oscuro
• Configura themeConfig.nav y themeConfig.sidebar según la estructura del catálogo
• La configuración de Mermaid debe establecer las variables del tema oscuro:

mermaid: {
  theme: 'dark',
  themeVariables: {
    primaryColor: '#1e3a5f',
    primaryTextColor: '#e0e0e0',
    primaryBorderColor: '#4a9eed',
    lineColor: '#4a9eed',
    secondaryColor: '#2d4a3e',
    tertiaryColor: '#2d2d3d',
    background: '#1a1a2e',
    fondoPrincipal: '#1e3a5f',
    bordeNodo: '#4a9eed',
    fondoClúster: '#16213e',
    colorTítulo: '#e0e0e0',
    fondoEtiquetaBorde: '#1a1a2e'
  }
}

Modo oscuro de Mermaid: corrección de tres capas

Capa 1: Variables del tema (en config.mts)

Se configuran mediante ` mermaid.themeVariables ` tal y como se muestra arriba.

Capa 2: Modificaciones de CSS (custom.css)

Aplica !important a los elementos SVG de Mermaid:

.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; }

Capa 3: Sustitución de estilos en línea (theme/index.ts)

Los atributos de estilo en línea de Mermaid anulan todo lo demás. Utiliza onMounted + sondeo para sustituirlos:

import { onMounted } from 'vue'

// En setup()
onMounted(() => {
  let intentos = 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 (++intentos >= 20) clearInterval(fix)
  }, 500)
})

Utiliza setup() con onMounted, NO enhanceApp() — el DOM no existe durante el SSR.

Zoom al hacer clic en los diagramas de Mermaid

Envuelve cada contenedor .mermaid en un contenedor en el que se pueda hacer clic y que abra una ventana modal a pantalla completa:

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 del modal:

.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); }

Reglas de posprocesado

Antes de la compilación con VitePress, analiza todos los archivos .md y corrige:

• Sustituir
por
(compatibilidad con el compilador de plantillas de Vue)
• Encerrar los en comillas invertidas fuera de los bloques de código
• Asegurarse de que cada página tenga un frontmatter YAML con título y descripción

Compilar

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

El resultado se guarda en wiki-site/.vitepress/dist/.

Problemas conocidos

• Mermaid se renderiza de forma asíncrona: los SVG aún no existen cuando se ejecuta onMounted. Hay que realizar un sondeo.
• La opción del compilador isCustomElement para elementos sin formato provoca fallos más graves: NO la utilices
• El texto de los nodos en Mermaid utiliza un estilo en línea con la máxima especificidad — el CSS por sí solo no lo soluciona
• enhanceApp() se ejecuta durante el SSR cuando el documento aún no existe; utiliza únicamente setup()