詳細ページ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を含める: 記事タイトルは既にヘッダーに表示されており重複