Wiki VitePress Packager

Transforme arquivos Markdown de wiki gerados em um site estático VitePress polido com tema escuro e diagramas Mermaid interativos.

Quando Usar

• O usuário pede para "construir um site" ou "empacotar como VitePress"
• O usuário executa o comando /deep-wiki:build
• O usuário deseja uma saída HTML navegável das páginas de wiki geradas

Estrutura do VitePress

Gere a seguinte estrutura em um diretório wiki-site/:

wiki-site/
├── .vitepress/
│   ├── config.mts
│   └── theme/
│       ├── index.ts
│       └── custom.css
├── public/
├── [generated .md pages]
├── package.json
└── index.md

Requisitos de Configuração (config.mts)

• Use o wrapper withMermaid de vitepress-plugin-mermaid
• Defina appearance: 'dark' para tema apenas escuro
• Configure themeConfig.nav e themeConfig.sidebar da estrutura do catálogo
• A configuração do Mermaid deve definir variáveis de tema escuro:

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 em Modo Escuro: Correção de Três Camadas

Camada 1: Variáveis de Tema (em config.mts)

Definidas via mermaid.themeVariables, como mostrado acima.

Camada 2: Substituições de CSS (custom.css)

Alvo de elementos SVG do Mermaid com !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; }

Camada 3: Substituição de Estilo Inline (theme/index.ts)

Atributos de estilo inline do Mermaid style substituem tudo. Use onMounted + polling para substituí-los:

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() com onMounted, NÃO enhanceApp() — o DOM não existe durante o SSR.

Clique para Zoom em Diagramas Mermaid

Envolva cada contêiner .mermaid em um wrapper clicável que abre um modal em tela cheia:

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

Regras de Pós-Processamento

Antes do build do VitePress, escaneie todos os arquivos .md e corrija:

• Substitua <br/> por <br> (compatibilidade com o compilador de template Vue)
• Envolva parâmetros genéricos <T> soltos em crases fora dos blocos de código
• Garanta que cada página tenha frontmatter YAML com title e description

Build

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

A saída vai para wiki-site/.vitepress/dist/.

Gotchas Conhecidos

• O Mermaid renderiza de forma assíncrona — SVGs não existem quando onMounted é acionado. É preciso fazer polling.
• A opção do compilador isCustomElement para <T> soltos causa falhas piores — NÃO a use.
• O texto de nós no Mermaid usa style inline com a maior especificidade — o CSS sozinho não resolverá.
• enhanceApp() é executado durante o SSR, onde document não existe — use apenas setup().

Quando Usar

Esta habilidade é aplicável para executar o fluxo de trabalho ou ações descritas na visão geral.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.

…