リッチコンテンツ表示スタックの確定
背景
現状 Parlourite Notes の Markdown レンダリングは Astro デフォルトの Shiki (シンタックスハイライト) のみで、以下の表示機能が未実装:
- コードブロックのコピーボタン (
docs/handoverにて要求あり) - 数式表示 (KaTeX/MathJax)
- 図表 (Mermaid)
- 脚注・タスクリスト等の GFM 拡張
- 外部リンクへの
target="_blank"およびrel属性自動付与 - テーブルのモバイル横スクロール対応
これらを個別に追加すると、都度 astro.config.mjs の変更、依存関係の
整合、CSS 調整が発生し、リファクタコストが積み重なる。技術ブログとして
必要な表示スタックを一度に確定し、以降の新規要件で追加が発生しにくい
状態にする。
決定
1. 採用ライブラリ一覧
| 用途 | ライブラリ | 選定理由 |
|---|---|---|
| コードブロック | astro-expressive-code | コピー機能標準搭載、Shiki 互換、Astro 公式相当の信頼性 |
| 数式 | remark-math + rehype-katex | SSR描画で JS バンドル削減、KaTeX は MathJax より軽量 |
| 図表 | mermaid (公式) | 業界標準、クライアント描画 |
| GFM 拡張 | remark-gfm | 脚注・タスクリスト・打消し線・テーブル |
| 外部リンク処理 | rehype-external-links | target/rel 自動付与のデファクト |
| 見出し ID 付与 | rehype-slug | TOC ADR で採用済み |
| テーブル横スクロール | 自作 remark プラグイン | <table> を <div class="table-wrap"> でラップ |
2. astro.config.mjs 設定方針
markdown.remarkPlugins:remark-math,remark-gfm, テーブルラッパmarkdown.rehypePlugins:rehype-slug,rehype-katex,rehype-external-links- Shiki は
astro-expressive-codeに統合されるため、markdown.syntaxHighlightは無効化
3. Mermaid 描画方針
- クライアント描画を採用 (SSR は依存重量とビルド時間の面で不利)
content-visibility: autoを適用し、画面外の図表の初期描画コストを抑制- Mermaid スクリプトは詳細ページで
<code class="language-mermaid">が 存在する時のみ動的 import
4. KaTeX スタイル
katex/dist/katex.min.cssをBaseHead.astroに条件付きロード (ページに.katexが含まれる場合のみ) は複雑化するため、 詳細ページのレイアウトで無条件ロードする- サイズ影響: KaTeX CSS は約 23KB (gzip) 程度で許容範囲
5. rehype-external-links 設定
target: '_blank'rel: ['noopener', 'noreferrer']- 内部リンク (相対 URL および同一オリジン) は対象外
6. テーブルラッパプラグイン
- 全
<table>を<div class="table-wrap" style="overflow-x: auto;">で 自動ラップ - モバイルで横スクロールを可能にし、レイアウト崩れを防止
7. 導入順序
astro-expressive-code(最も要求頻度が高い)remark-gfm+rehype-slug+rehype-external-links(低リスク)remark-math+rehype-katex(数式)- Mermaid (クライアント JS のため最後)
- テーブルラッパ (最小影響、いつでも可)
理由
astro-expressive-code: コピー機能の自作を避けられる。Shiki との 互換性・テーマ連動・フレーム表示 (ファイル名タブ) が標準搭載。 「特殊な実装はしない」原則に合致- KaTeX 選択: MathJax は歴史的に強力だが、SSR 対応、バンドルサイズ、 レンダリング速度で KaTeX が優位。技術ブログ用途では KaTeX で十分
- Mermaid クライアント描画: SSR 対応の
@mermaid-js/mermaidは 依存が重く、ビルド時間が顕著に増加する。Parlourite の記事量では クライアント描画で十分な UX - remark-gfm 採用: GitHub 標準の Markdown 拡張であり、執筆時に 自然に使える記法 (脚注・タスクリスト) を許容
- 一括導入: 個別追加でリファクタコストが積み重なるより、一度で 確定する方が長期的に安価
影響
astro.config.mjsに上記プラグインを追加package.jsonに依存追加:astro-expressive-code,remark-math,rehype-katex,remark-gfm,rehype-external-links,rehype-slug,mermaidBaseHead.astro(または詳細ページレイアウト) に KaTeX CSS ロード追加- 詳細ページに Mermaid 動的 import スクリプト追加
- 自作 remark プラグイン
src/lib/remark/table-wrap.tsを新規作成 - コードブロック UI の詳細は別 ADR (
code-block-ui-policy) で決定
代替案(却下)
- コピーボタンの自作実装:
astro-expressive-codeで十分。車輪の 再発明を避ける - MathJax: 上記理由により却下
- Mermaid SSR: ビルド時間増加のデメリットが便益を上回る
markdown-itへの切替: Astro は remark/rehype 前提であり、 切替コストが便益を上回る- プラグイン都度追加: 都度リファクタコストが発生し、天井の低い セッション運用では特に不利