ダークモードでコードハイライトが崩れる問題の診断

WordPress プラグイン「Markdown Renderer for GitHub」で、ダークモード設定時にフロントエンド（投稿表示画面）のコードハイライトが正しく表示されない問題に遭遇しました。エディタプレビューでは正常なのに、実際の投稿画面では背景色がライトモードのまま、という症状です。 ## 症状 - **エディタプレビュー**: ダークモードの背景色を正しく表示 - **フロントエンド投稿画面**: ライトモードの背景色で表示 - エラーログ: `TypeError: this.extractPlainTextFromHighlighted is not a function`（後にキャッシュ問題と判明） ## 原因 複数の原因が重なっていました。 ### 原因1: CSS `inherit` による上書き `assets/css/gfmr-code-blocks.css` で次のように指定していました。 ```css .shiki, .shiki pre, .shiki code { background-color: inherit !important; } ``` Shiki が生成する HTML のインラインスタイル（`background-color: #0d1117` など）を、この CSS が上書きしていました。`inherit` により親要素の背景色を強制的に継承させていたのが根本原因です。 ### 原因2: CSS 変数値とテーマ色の不一致 - CSS 変数 `--gfmr-code-bg: #161b22`（定義） - Shiki github-dark テーマ: `#0d1117`（実際） この差異により、テーマの一貫性が失われていました。 ### 原因3: JavaScript キャッシュ ブラウザが古い JavaScript を配信しており、修正コードが読み込まれていませんでした。 ## 直し方 ### Fix 1: CSS の `inherit` を CSS 変数に変更 `assets/css/gfmr-code-blocks.css`: ```css /* Before */ .shiki, .shiki pre, .shiki code { background-color: inherit !important; } /* After */ .shiki, .shiki pre { background-color: var(--gfmr-code-bg) !important; } .shiki code { background-color: transparent !important; } ``` `.shiki code` を分離することで、構文色が正しく表示されるようにしました。 ### Fix 2: CSS 変数値をテーマ色に統一 `assets/css/gfmr-theme-variables.css` のダークテーマの `--gfmr-code-bg` を更新しました。 ```css /* Dark theme */ --gfmr-code-bg: #0d1117; /* #161b22 → #0d1117 */ /* System theme (dark) */ --gfmr-code-bg: #0d1117; /* #161b22 → #0d1117 */ ``` CSS 変数を「正（Single Source of Truth）」と位置づけ、Shiki テーマ値と完全に一致させました。 ### Fix 3: エディタプレビューのダークモード背景 `blocks/markdown/editor.css`（新規追加）: ```css .gfmr-dark.gfmr-markdown-rendered-preview pre, .gfmr-dark.gfmr-markdown-rendered-preview pre.shiki, .gfmr-dark.gfmr-markdown-rendered-preview .shiki { background-color: #0d1117 !important; } ``` WYSIWYG の一貫性を確保しました。 ### Fix 4: ブラウザキャッシュのクリア 古い JavaScript・CSS が配信されていたため、ブラウザキャッシュをクリアして最新を読み込むよう案内しました。 ## 学び ### CSS カスケードの複雑さ `inherit !important` は非常に強力で、インラインスタイルさえ上書きします。テーマシステムが複数層ある場合は、各層の責務を明確に分離する必要があります。 ### テーマ値の一貫性管理 サーバーサイド（Shiki テーマ）とクライアントサイド（CSS 変数）でカラー値が異なると、維持管理が難しくなります。「正の源泉（Single Source of Truth）」を決めて統一することが重要です。 ### 二重処理のパフォーマンス影響 修正の過程で、サーバー側で生成・保存した HTML と表示時の現在のテーマ設定が異なる場合、クライアント側で全コードブロックを再ハイライトしていることが分かりました（二重処理）。許容範囲内（500〜800ms）ですが、今後の最適化課題として残しています。 ### デバッグ手法 - ブラウザコンソール（Chrome DevTools）で実行フローを追跡 - Network タブでリソース読み込みを確認 - Elements タブで CSS の計算値（computed styles）を検査 これらが、CSS・JavaScript・テーマシステムにまたがる問題の解決に有効でした。 ## 確認手順 1. WordPress 管理画面の設定でダークテーマを選択 2. 投稿・ページをフロントエンドで表示 3. コードブロックの背景色（ダーク #0d1117）とシンタックス色（Shiki のスタイル）を確認 4. ライトテーマに切り替えて同様に確認 5. エディタプレビューでも正常に表示されることを確認 6. ブラウザキャッシュをクリアして再確認 --- これは [Markdown Renderer for GitHub](/markdown-renderer-for-github/) に実装されています。

.shiki,
.shiki pre,
.shiki code {
    background-color: inherit !important;
}

/* Before */
.shiki,
.shiki pre,
.shiki code {
    background-color: inherit !important;
}

/* After */
.shiki,
.shiki pre {
    background-color: var(--gfmr-code-bg) !important;
}

.shiki code {
    background-color: transparent !important;
}

/* Dark theme */
--gfmr-code-bg: #0d1117;  /* #161b22 → #0d1117 */

/* System theme (dark) */
--gfmr-code-bg: #0d1117;  /* #161b22 → #0d1117 */

.gfmr-dark.gfmr-markdown-rendered-preview pre,
.gfmr-dark.gfmr-markdown-rendered-preview pre.shiki,
.gfmr-dark.gfmr-markdown-rendered-preview .shiki {
    background-color: #0d1117 !important;
}