decisiondecided

詳細ページTOCサイドバーの採用

背景

記事詳細ページには現在サイドバーが存在せず、以下の課題があった:

  • ADR や Reference など長い記事で、現在位置が把握できない
  • 章間のジャンプ手段がなく、目的の見出しまでスクロールが必要
  • 一覧ページには type/tag フィルタサイドバーがあるが、詳細ページには 対応する左カラムパーツがなく、レイアウトの一貫性が欠ける
  • 詳細ページで一覧用の type/tag フィルタを表示するのは文脈的に不適切

技術ブログ・ドキュメントサイト (VitePress, Docusaurus, MDN, Notion) で 標準的な「章一覧 (TOC) を左または右サイドバーに表示する」パターンを Parlourite に導入する。

決定

1. 左サイドバーに TOC を配置

詳細ページの左サイドバーとして TocSidebar.astro を新設し、 SidebarShell.astro の中に注入する。位置・折りたたみ挙動は 一覧ページのフィルタサイドバーと完全共通。

2. 抽出対象と生成方法

  • 抽出対象: <h2> と <h3> のみ (<h1> は記事タイトル、 <h4> 以下は含めない)
  • 生成方法: Astro 標準 API entry.render() の戻り値 headings: Array<{ depth, slug, text }> を利用
  • 追加依存: なし (Astro 標準機能のみ)

3. 表示仕様

  • リストは h2 → h3 の階層構造で表示 (h3 は 16px インデント)
  • 各項目は <a href="#{slug}"> でアンカーリンク
  • スクロール: scroll-behavior: smooth によるスムーススクロール
  • アクティブハイライト: IntersectionObserver で現在ビューポート上部に ある見出しを検出し、対応する TOC 項目に data-active="true" を付与
  • スティッキー挙動: SidebarShell の position: fixed を継承

4. アンカー生成

  • 見出しへの id 付与は rehype-slug で行う (astro.config.mjs の markdown.rehypePlugins に追加)
  • スラッグ規則は rehype-slug デフォルト (小文字化、空白ハイフン化、 日本語はそのまま)

5. モバイル対応

  • モバイル (<768px) では SidebarDrawer.astro の中身に TOC を渡す
  • ハンバーガーメニューから開く際、詳細ページでは TOC、一覧ページでは フィルタが表示される (slot 切替)

6. TOC が空の場合の挙動

  • headings の h2/h3 抽出結果が 0 件の場合、TocSidebar.astro は 何も描画しない (SidebarShell ごと非表示)
  • 短い記事や type: log などでは自然にサイドバーなしのレイアウトになる

理由

  • 左サイドバー選択: Parlourite は ADR 中心の技術ブログであり、 ドキュメントサイト寄りの用途。Medium/Zenn 風の右サイドバー TOC より、 VitePress/Docusaurus 風の左サイドバーが文脈に合う
  • h2/h3 のみ: h4 以下を含めると TOC が長大化し、ナビゲーション性が 逆に低下する。ADR の章構成 (背景/決定/理由/影響/代替案) は h2 で 十分表現可能
  • Astro 標準 API 使用: remark-toc などの追加依存を避け、 「シンプルで手堅い実装パターン」原則に従う
  • IntersectionObserver: スクロールイベント方式より高性能かつ 実装が簡潔。ブラウザ標準 API のため互換性も広い
  • rehype-slug: 見出しへの id 付与のデファクトスタンダード。 Astro Docs 公式サイトでも採用

影響

  • astro.config.mjs に rehype-slug を追加
  • TocSidebar.astro を新規作成
  • 記事詳細ページ (src/pages/[lang]/[id].astro) を、SidebarShell + TocSidebar を含むレイアウトに変更
  • SidebarDrawer.astro の中身 slot 化により、モバイルでも TOC が 参照可能になる
  • 短い記事 (h2/h3 なし) では自動的にサイドバー非表示となり、 本文がより広く見える

代替案(却下)

  • 右サイドバー TOC (Medium/Zenn 方式): 一覧ページの左サイドバーと レイアウト対称性が崩れる。SidebarShell の共通化が困難
  • 本文内先頭に TOC ブロック: スクロール追従できず、ナビゲーション 性能が低い
  • remark-toc プラグイン導入: Astro 標準の headings で十分な ため、追加依存の理由がない
  • h2〜h6 全階層表示: リストが縦に長くなりすぎ、視認性低下
  • h1 を含める: 記事タイトルは既にヘッダーに表示されており重複