ghost-toc-plugin プレビュー

Name: ghost-toc-plugin
Author: GreedyLabs

左パネルでオプションを変えてみてください。目次がリアルタイムで再描画され、埋め込みコードも一緒に更新されます。スクロールすると現在のセクションが強調されます。

はじめに

ghost-toc-plugin は、コード1行で Ghost ブログにフローティング目次を追加できる、軽量（約3KB）で依存関係のないウィジェットです。Ghost 向けとして始まりましたが、Notion ベースのブログでも動作し、スクリプトを追加できる場所ならどこでも動きます。記事の見出しを読み取って目次を自動生成し、スクロールに追従して現在の見出しを強調します。このページがそのまま実例で、横に見える目次が実際に動くウィジェットです。

インストール

ビルド工程もテーマ編集も不要。下のスニペットを一度貼り付けるだけです：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-toc-plugin@1/toc.css">
<script src="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-toc-plugin@1/toc.min.js"
        data-content=".gh-content"
        data-headings="h2,h3"
        data-title="目次"></script>

コードインジェクション

Ghost では Settings → Code injection → Site Footer に貼り付けます。Notion ベースのホスティングなら、カスタムコード欄に追加します。oopy はサイト設定の head/footer コード欄、super.so は Custom Code 領域があり、そこで data-content を .notion-page-content にします。その他のサイトでは閉じタグ </body> の直前に置きます。自身の data-* オプションを読めるよう、async や defer は付けません。

オプション設定

動作はすべてスクリプトタグの data-* 属性で設定します: 本文セレクタ、含める見出し、タイトル、位置などを指定できます：

data-content=".gh-content"
data-headings="h2,h3"
data-position="right"
data-min-width="1200"
data-top="100"

カスタマイズ

色と位置は自由に調整できます。すべてのクラスと CSS 変数は greedylabs-ghost-toc で名前空間化されており、テーマと衝突しません。

配色

現在の項目の色は、既定で Ghost テーマのアクセント色（--ghost-accent-color）に従います。変更するには data-accent を指定するか、CSS 変数を上書きします。ウィジェットはライト／ダークの既定値を備え、システムテーマに自動で合わせます。ダークモードの可読性を高めたい場合は、ダークのときだけ色を上書きしてください, 単一の固定値ではライトで不自然になります：

@media (prefers-color-scheme: dark) {
  .greedylabs-ghost-toc {
    --greedylabs-ghost-toc-muted: #c9d1d9;
    --greedylabs-ghost-toc-border: rgba(255,255,255,.22);
  }
}

位置

data-position で左右、data-top で上の余白、data-gap で本文との間隔、data-width でパネル幅を指定します。画面が data-min-width より狭い場合や横にスペースがない場合、目次は自動的に隠れます。

よくある質問

このウィジェットでサイトが遅くなりますか？

ほとんど影響ありません。約3KBで依存関係も外部リクエストもなく、スクロールは passive リスナーで受け取り、requestAnimationFrame でフレームごとに一度だけ計算します。遅延読み込み画像や giscus などでドキュメントの高さが変わったときだけ ResizeObserver で再計算します。

目次が表示されないのはなぜですか？

3点を確認してください。data-content セレクタが実際の本文コンテナと一致しているか、見出しが2つ以上あるか（それ未満では生成されません）、画面が data-min-width（既定1200px）より広く本文の横にパネルが入る余地があるか。狭い画面やモバイルでは意図的に隠れます。

h4 のような深い見出しも目次に含められますか？

はい。data-headings に入れたいタグをカンマ区切りで指定します（例: h2,h3,h4）。リストに表示する見出しレベルを自由に選べます。

おわりに

ghost-toc-plugin は MIT ライセンスのオープンソースで、コードと Issue は GitHub にあります。左パネルでオプションを変えてライブプレビューを確認し、気に入ったら埋め込みコードをコピーしてください。お役に立てたら、コーヒーを一杯いただけると嬉しいです ☕。