Mermaid図がWeb上で表示されない問題の調査と対応方針

問題の概要

現象

Markdownエディタのプレビュー: Mermaidコードブロックが図として正しく表示される
実際のWebページ: Mermaidコードブロックがそのまま表示され、図としてレンダリングされない

影響範囲

既存の記事（例：/2025-10-19/claude-skills-complete-guide）
新規作成した記事（例：/2025-11-20/nvidia-fy26-q3-earnings）

サンプルコード

\`\`\`mermaid
graph LR
    A[Q3売上高<br/>570億ドル] --> B[前年比<br/>+62%]
    A --> C[前四半期比<br/>+22%]
\`\`\`

原因調査

1. 環境確認

package.jsonの状態

{
  "dependencies": {
    "@nuxt/content": "^3.7.1",
    "nuxt": "^4.1.2",
    // mermaidパッケージが削除されている
  }
}

問題点: mermaidパッケージがインストール後に削除されている可能性

コンポーネントの存在確認

✅ app/components/content/ProseCode.vue は作成済み
❓ コンポーネントが正しく読み込まれているか不明

2. Nuxt Contentのレンダリング仕組み

Nuxt Contentでコードブロックをカスタマイズするには：

components/content/ProseCode.vue を作成（✅ 完了）
Mermaidライブラリをインストール（❓ パッケージが消えている）
サーバー側でプリレンダリング、またはクライアント側で動的レンダリング

3. 考えられる原因

原因A: Mermaidパッケージの欠落

mermaidパッケージがインストールされたが、その後削除または除外された可能性

原因B: ProseCode.vueが認識されていない

Nuxt ContentがProseCode.vueを正しく読み込んでいない可能性

原因C: クライアント側レンダリングの問題

Mermaidはブラウザ側でSVGを生成する必要があるが、SSR（サーバーサイドレンダリング）との競合

原因D: Nuxt Content設定の不足

nuxt.config.tsまたはcontent.config.tsでMermaid用の設定が必要

対応方針

フェーズ1: 現状確認（優先度: 高）

1-1. パッケージの再確認

cd apps/web
pnpm list mermaid

mermaidがインストールされているか確認
なければ再インストール: pnpm add mermaid

1-2. ProseCode.vueの読み込み確認

ブラウザの開発者ツールで以下を確認：

コンポーネントがマウントされているか
エラーメッセージの有無
ネットワークタブでmermaid.jsが読み込まれているか

1-3. 既存記事での動作確認

/2025-10-19/claude-skills-complete-guide を開いて：

ブラウザのコンソールにエラーが出ていないか
DOMにmermaid関連の要素が存在するか

フェーズ2: 代替アプローチの検討（優先度: 中）

アプローチA: Nuxt Mermaidモジュールの利用

公式のNuxtモジュールが存在しないため、カスタム実装が必要

アプローチB: rehype/remarkプラグインの利用

pnpm add rehype-mermaid

nuxt.config.tsに追加：

export default defineNuxtConfig({
  content: {
    markdown: {
      rehypePlugins: [
        'rehype-mermaid'
      ]
    }
  }
})

アプローチC: クライアントサイドのみでレンダリング

ProseCode.vueを<ClientOnly>でラップ：

<ClientOnly>
  <div v-if="language === 'mermaid'" ref="mermaidContainer"></div>
</ClientOnly>

アプローチD: 事前レンダリング（ビルド時）

ビルド時にMermaidをSVGに変換してHTMLに埋め込む

メリット: 高速表示、SEO対応
デメリット: ビルド時間の増加

フェーズ3: 実装と検証（優先度: 高）

3-1. 推奨アプローチ

アプローチC + パッケージ再インストールを推奨

理由：

シンプルで実装が容易
クライアント側レンダリングでSSRの問題を回避
既存のProseCode.vueを活用できる

3-2. 実装手順

mermaidパッケージを再インストール
ProseCode.vueをClientOnlyでラップ
開発サーバーを再起動
既存記事と新規記事で動作確認

3-3. 検証項目

Mermaid図が正しく表示される
コンソールにエラーが出ない
既存記事も正常に表示される
ビルドが成功する
本番環境でも動作する

フェーズ4: ドキュメント化（優先度: 低）

成功した方法をREADME.mdまたはCLAUDE.mdに追記：

Mermaidの使い方
トラブルシューティング
制限事項

次のアクション

即座に実行すべきこと

pnpm list mermaidでパッケージ確認
ブラウザの開発者ツールでエラー確認
ProseCode.vueの読み込み確認

問題が解決しない場合

rehype-mermaidプラグインを試す
別のMermaid実装方法を検討
一時的にDraw.ioや画像埋め込みで対応

参考情報

参考記事

Nuxt Content公式ドキュメント: https://content.nuxt.com/
Mermaid公式ドキュメント: https://mermaid.js.org/

類似の問題報告

GitHub Issue検索: "nuxt content mermaid"
Stack Overflow: "mermaid diagram not rendering nuxt"

実装完了

対応内容

✅ mermaidパッケージの確認（v11.12.1インストール済み）
✅ ProseCode.vueを再作成し、以下の改善を実施：
- <ClientOnly>でラップしてSSR問題を回避
- Dynamic importでクライアント側のみでmermaidを読み込み
- エラーハンドリングを強化

検証方法

開発サーバーを再起動して確認：

cd apps/web
pnpm dev

ブラウザで以下のページを開いて図が表示されるか確認：

トラブルシューティング

図が表示されない場合：

ブラウザの開発者ツール（F12）を開く
コンソールにエラーが出ていないか確認
ネットワークタブでmermaidが読み込まれているか確認

更新履歴

2025-11-20 11:44: ProseCode.vue実装完了、ClientOnly対応
2025-11-20: 初回作成、問題の特定と対応方針の策定