2025/01/06

【公式ライブラリ使用】microCMSで目次を簡単実装

📑 目次

こんにちは、KnowHack（ノウハック）です。

今回は microCMS が公式で公開しているリッチエディタ向けライブラリ を使って、目次機能を簡単に実装する方法を紹介します。
このライブラリは、画像最適化・シンタックスハイライト・目次生成などが簡単に実現できる便利ツールです。

公式ドキュメント: microcms-rich-editor-handler

【ライブラリ公開】
リッチエディタに対して、下記のような処理を簡単に実行できるライブラリを公開しました🚀

✅複数の拡張子/サイズで画像を配信してパフォーマンスを良くしたい
✅コードブロックにシンタックスハイライトを当てたい
✅見出し要素から目次を生成したいhttps://t.co/nBrcCxvsqZ
— microCMS｜APIベースのヘッドレスCMS (@micro_cms) December 23, 2024

今回の記事では、目次機能にフォーカスして、Astro での例を中心に解説します。
とはいえ、Next.js などの他のフレームワークでも使い方はほとんど同じなので、参考にしてみてください。

microCMS リッチエディタ用ライブラリとは？

microcms-rich-editor-handler は、以下のような機能を備えています。

画像の最適化
?fm=webp や ?w=幅 といったパラメータを自動的に挿入し、軽量化する
シンタックスハイライト
コードブロックのハイライトを手軽に実装できる
目次生成
見出しタグ（h1〜h6）を元に目次データを作ってくれる

設定はオプションごとに選べるため、「今回は目次だけ使いたい」というケースにもピッタリです。

目次実装のコード例 (Astro)

では、具体的にどのように使うかを見てみましょう。

[postId].astro

---
const { postId } = Astro.params;
const post = await getPostBySlug(postId);
const {
  html,
  data: { toc },
} = await microCMSRichEditorHandler(post.content, {
  extractors: {
    toc: [
      tocExtractor({
        ignoreLevels: [4, 5], // 無視したい見出しのレベル
      }),
      { phase: "before" }],
  },
});
---

<Layout>
  {/* 目次 */}
  <Toc toc={toc} />
  {/* 本文 */}
  <div class="rich-text mt-8" set:html={html} />
</Layout>

tocExtractor を使うことで、指定した見出しレベル（h4 や h5 など）を無視できます。
html には、リッチエディタの内容がレンダリング済みのHTML文字列が入ります。これを <div set:html={html} /> で描画することで、記事本文が表示されます。

目次の描画

続いて、生成された toc を使って目次を表示するコード例です。

Toc.astro

---
type Props = {
  toc: {
    level: number;
    id: string;
    text: string;
  }[];
};

const { toc } = Astro.props;
---

<div>
  <h2 class="mb-4 font-semibold">📑 目次</h2>
  <nav class="text-sm">
    <ul class="space-y-1">
      {
        toc.map((item) => {
          return (
            <li data-level={item.level} class="toc-list">
              <a href={`#${item.id}`}>
                {item.text}
              </a>
            </li>
          );
        })
      }
    </ul>
  </nav>
</div>

toc は見出し階層（level）、アンカーになる id、実際のテキスト text を持っています。
単純に ul > li でリスト化すれば、シンプルな目次機能の完成です。

もう少し発展させるには？

スクロールスパイ機能
目次のリンクをクリックして飛んだだけでなく、「読んでいる見出しに合わせて目次項目をハイライト」する機能を追加できます。Astro でも JavaScript を導入すれば実装可能ですし、フレームワークによってはプラグインやライブラリがあるので試してみましょう。
階層ごとにインデントを変える
level: 2 (h2) と level: 3 (h3) でマージンやスタイルを変え、目次を階層的に表示すると見やすくなります。
見出しの文言をカスタマイズ
長すぎる見出しを短縮表示したり、アイコンを入れたりすることも可能。

よくあるトラブル・疑問点

アンカー位置がずれてしまう
固定ヘッダーを使っているサイトだと、リンク先に飛んだとき上部が隠れてしまう場合があります。これは scroll-margin-top や JavaScript での補正、もしくはCSSで padding-top を追加するなどの方法で対応できます。
見出しが多すぎてごちゃごちゃする
ignoreLevels や一部の見出しを除外する設定を利用し、目次をすっきりさせましょう。
他のライブラリ（シンタックスハイライトなど）と併用したい
responsiveImageTransformer() や syntaxHighlightTransformer() を併せて使う例が公式ドキュメントにあるので参照してみてください。