Пакетный инструмент Wiki VitePress

Преобразует сгенерированные файлы Markdown вики в отлаженный статический сайт VitePress с темной темой и интерактивными диаграммами Mermaid.

Когда активировать

• Пользователь запрашивает «создать сайт» или «упаковать в формат VitePress»
• Пользователь запускает команду /deep-wiki:build
• Пользователь хочет получить HTML-код, доступный для просмотра в браузере, на основе сгенерированных страниц вики

Структура VitePress

Сгенерируйте следующую структуру в каталоге wiki-site/:

wiki-site/
├── .vitepress/
│   ├── config.mts
│   └── theme/
│       ├── index.ts
│       └── custom.css
├── public/
├── [сгенерированные страницы .md]
├── package.json
└── index.md

Требования к конфигурации (config.mts)

• Используйте обёртку withMermaid из vitepress-plugin-mermaid
• Установите parameter appearance: 'dark' для темной темы
• Настройте themeConfig.nav и themeConfig.sidebar в соответствии со структурой каталога
• В конфигурации Mermaid необходимо задать переменные для тёмной темы:

mermaid: {
  theme: 'dark',
  themeVariables: {
    primaryColor: '#1e3a5f',
    primaryTextColor: '#e0e0e0',
    primaryBorderColor: '#4a9eed',
    lineColor: '#4a9eed',
    secondaryColor: '#2d4a3e',
    tertiaryColor: '#2d2d3d',
    background: '#1a1a2e',
    основной фон: '#1e3a5f',
    граница узла: '#4a9eed',
    фон кластера: '#16213e',
    цвет заголовка: '#e0e0e0',
    edgeLabelBackground: '#1a1a2e'
  }
}

«Русалка» в тёмном режиме: исправление трёх слоёв

Слой 1: Переменные темы (в файле config.mts)

Задаются через mermaid.themeVariables, как показано выше.

Уровень 2: Переопределения CSS (custom.css)

Применяйте !important к элементам SVG в 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; }

Слой 3: Замена встроенных стилей (theme/index.ts)

Атрибуты встроенных стилей Mermaid переопределяют всё остальное. Используйте onMounted и опрос для их замены:

import { onMounted } from 'vue'

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

Используйте setup() с onMounted, а НЕ enhanceApp() — DOM не существует во время SSR.

Увеличение диаграмм Mermaid при нажатии

Оберните каждый контейнер .mermaid в кликабельный контейнер, который открывает полноэкранное модальное окно:

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 модального окна:

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

Правила постобработки

Перед сборкой VitePress просканируйте все файлы .md и исправьте:

• Заменить
на
(совместимость с компилятором шаблонов Vue)
• Оборачивать неогороженные общие параметры в обратные кавычки вне блоков кода
• Убедитесь, что каждая страница имеет YAML-фронтматтер с заголовком и описанием

Скомпилируйте

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

Результат выводится в папку wiki-site/.vitepress/dist/.

Известные проблемы

• Mermaid выполняет рендеринг асинхронно — SVG-файлы ещё не существуют на момент срабатывания onMounted. Необходимо выполнять опрос.
• Параметр компилятора `isCustomElement ` для «голого» приводит к более серьёзным сбоям — НЕ используйте его
• Текст узла в Mermaid использует встроенный стиль с максимальной специфичностью — одного CSS для исправления этого недостаточно
• enhanceApp() запускается во время SSR, когда документ ещё не существует — используйте только setup()