Wiki VitePress Packager

Transformez les fichiers Markdown wiki générés en un site statique VitePress soigné, doté d’un thème sombre et de diagrammes Mermaid interactifs.

Quand l'activer

• L'utilisateur demande de « créer un site » ou de « générer un package VitePress ».
• L'utilisateur exécute la commande /deep-wiki:build
• L'utilisateur souhaite obtenir un fichier HTML consultable à partir des pages wiki générées

Structure de base VitePress

Générez la structure suivante dans un répertoire wiki-site/:

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

Exigences de configuration (config.mts)

• Utilisez le wrapper withMermaid de vitepress-plugin-mermaid
• Définissez appearance: 'dark' pour un thème exclusivement sombre
• Configurez themeConfig.nav et themeConfig.sidebar en fonction de la structure du catalogue
• La configuration Mermaid doit définir les variables du thème sombre :

mermaid: {
  theme: 'dark',
  themeVariables: {
    primaryColor: '#1e3a5f',
    primaryTextColor: '#e0e0e0',
    primaryBorderColor: '#4a9eed',
    lineColor: '#4a9eed',
    secondaryColor: '#2d4a3e',
    tertiaryColor: '#2d2d3d',
    background: '#1a1a2e',
    fondPrincipal : '#1e3a5f',
    bordureNœud : '#4a9eed',
    fondGroupe : '#16213e',
    couleurTitre : '#e0e0e0',
    edgeLabelBackground : '#1a1a2e'
  }
}

Mode sombre Mermaid : correction à trois couches

Couche 1 : variables de thème (dans config.mts)

Définies via ` mermaid.themeVariables ` comme indiqué ci-dessus.

Couche 2 : Remplacements CSS (custom.css)

Ciblez les éléments SVG de Mermaid avec !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; }

Couche 3 : Remplacement des styles en ligne (theme/index.ts)

Les attributs de style en ligne de Mermaid ont priorité sur tout le reste. Utilisez onMounted + un polling pour les remplacer :

import { onMounted } from 'vue'

// Dans 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)
})

Utilisez setup() avec onMounted, et NON enhanceApp() — le DOM n'existe pas pendant le SSR.

Zoom par clic pour les diagrammes Mermaid

Enveloppez chaque conteneur .mermaid dans un wrapper cliquable qui ouvre une fenêtre modale en plein écran :

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 de la fenêtre modale :

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

Règles de post-traitement

Avant la compilation avec VitePress, analysez tous les fichiers .md et corrigez :

• Remplacer
par
(compatibilité avec le compilateur de modèles Vue)
• Envelopper les par des guillemets inversés à l'extérieur des blocs de code
• S'assurer que chaque page comporte un frontmatter YAML avec un titre et une description

Créer

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

Le résultat est placé dans wiki-site/.vitepress/dist/.

Pièges connus

• Mermaid effectue le rendu de manière asynchrone — les fichiers SVG n'existent pas lorsque la méthode onMounted est déclenchée. Il faut effectuer une interrogation.
• L'option de compilation isCustomElement pour les éléments « bare » provoque des plantages plus graves — ne l’utilisez PAS
• Le texte des nœuds dans Mermaid utilise un style en ligne avec la spécificité la plus élevée — le CSS seul ne suffit pas à résoudre le problème
• La fonction`enhanceApp()` s'exécute pendant le SSR alors que le document n'existe pas — utilisez uniquement `setup()`