decisiondecided

リッチコンテンツ表示スタックの確定

背景

現状 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-katexSSR描画で JS バンドル削減、KaTeX は MathJax より軽量
図表mermaid (公式)業界標準、クライアント描画
GFM 拡張remark-gfm脚注・タスクリスト・打消し線・テーブル
外部リンク処理rehype-external-linkstarget/rel 自動付与のデファクト
見出し ID 付与rehype-slugTOC 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) 程度で許容範囲
  • target: '_blank'
  • rel: ['noopener', 'noreferrer']
  • 内部リンク (相対 URL および同一オリジン) は対象外

6. テーブルラッパプラグイン

  • 全 <table> を <div class="table-wrap" style="overflow-x: auto;"> で 自動ラップ
  • モバイルで横スクロールを可能にし、レイアウト崩れを防止

7. 導入順序

  1. astro-expressive-code (最も要求頻度が高い)
  2. remark-gfm + rehype-slug + rehype-external-links (低リスク)
  3. remark-math + rehype-katex (数式)
  4. Mermaid (クライアント JS のため最後)
  5. テーブルラッパ (最小影響、いつでも可)

理由

  • 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, mermaid
  • BaseHead.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 前提であり、 切替コストが便益を上回る
  • プラグイン都度追加: 都度リファクタコストが発生し、天井の低い セッション運用では特に不利