wiki-vitepress

Wiki VitePress パッケージャー

生成された Wiki の Markdown ファイルを、ダークテーマとインタラクティブな Mermaid 図を備えた、洗練された VitePress 静的サイトに変換します。

使用するタイミング

• ユーザーが「サイトを構築」または「VitePress としてパッケージ化」と依頼した場合
• ユーザーが /deep-wiki:build コマンドを実行した場合
• ユーザーが生成された Wiki ページを閲覧可能な HTML として出力したい場合

VitePress のスキャフォールディング

wiki-site/ ディレクトリに次の構造を生成します。

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

設定要件（config.mts）

• vitepress-plugin-mermaid の withMermaid ラッパーを使用します
• ダークテーマのみを使用するため、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',
    mainBkg: '#1e3a5f',
    nodeBorder: '#4a9eed',
    clusterBkg: '#16213e',
    titleColor: '#e0e0e0',
    edgeLabelBackground: '#1a1a2e'
  }
}

Mermaid のダークモード：3 層の対策

レイヤー 1：テーマ変数（config.mts 内）

上記のとおり、mermaid.themeVariables で設定します。

レイヤー 2：CSS のオーバーライド（custom.css）

Mermaid の SVG 要素を !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; }

レイヤー 3：インラインスタイルの置換（theme/index.ts）

通常のインラインスタイルは、適切な作成者スタイルの !important ルールで上書きできます。レンダラーのテーマ設定とスコープ付き CSS を優先してください。すべての SVG の塗りや線を置き換えると、意味に応じた色が失われるため避けてください。特定バージョンの DOM に対する回避策が必要な場合は、範囲を限定したマウント済みフックを使い、アンマウント時およびルート変更時にタイマーやリスナーを破棄してください。

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

SSR 中は DOM が存在しないため、enhanceApp() ではなく onMounted を使って setup() を実行してください。

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.appendChild(el.cloneNode(true))
    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); }

モーダルのスケッチは未完成です。本番用 UI には、アクセシブルなボタンとダイアログの名前、Escape キーへの対応、フォーカスのトラップと復元、リスナーのクリーンアップが必要です。Markdown や図のコンテンツは信頼できない入力として扱ってください。描画の便宜のために任意の HTML／スクリプト実行を有効にせず、Mermaid の厳格なセキュリティを維持してください。

後処理のルール

VitePress のビルド前に、すべての .md ファイルをスキャンして、次の点を修正します。

• 有効な自己終了形式の <br/>／<br> マークアップは保持します。実際のコンパイラーエラーが発生した場合に限り、対象を限定して修正してください。コードフェンス内のテキストは書き換えないでください
• コードフェンスの外にある <T> 形式のジェネリックパラメーターはバッククォートで囲みます
• すべてのページに title と description を含む YAML フロントマターを設定します

ビルド

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

出力先は wiki-site/.vitepress/dist/ です。

既知の注意点

• Mermaid の描画は非同期です。onMounted の実行時には SVG がまだ存在しません。ポーリングが必要です。
• 裸の <T> に対するコンパイラーオプション isCustomElement は、より深刻なクラッシュを引き起こします。使用しないでください
• Mermaid のノードのテキストでは、最も優先度の高いインライン style が使われます。CSS だけでは修正できません
• enhanceApp() は document が存在しない SSR 中に実行されます。setup() のみを使用してください

使用するタイミング

このスキルは、概要で説明されているワークフローや操作を実行する場合に適用できます。

制限事項

• このスキルは、タスクが上記の説明の範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、成功基準が不足している場合は、作業を中断して確認を求めてください。