【Gatsby.js】記事に「目次」を追加するプラグイン「gatsby-remark-table-of-contents」の使い方

August 15, 2020

記事の読みやすさを向上させる「目次」を追加する。

mokuji

目次を追加したい

次のような目次を追加する方法を考える。

今回はGatsby.jsにこの目次を簡単に追加できるプラグインを紹介する。

前提条件

目次ボタンはhタグ内に#を使った「ページ内リンク」となるので

ページ内リンクを取り扱うプラグインとの併用がほぼ必須となっている。

私が合わせて使っているページ内リンクプラグインは次

gatsby-remark-autolink-headers | GatsbyJS

こちらの設置方法も記事にしてある。

【Gatsby.js】見出しにページ内リンクを設定するプラグイン「gatsby-remark-autolink-headers」 | Blog

gatsby-remark-table-of-contents

今回利用する「記事に目次を追加するGatsby.jsのプラグイン」である。

動作としてはmarkdownの中に目次を挿入するという方法をとっており.mdファイルにコードを追加しておくだけで自動的に目次を製作してくれる。

markdown形式で記述される目次になるためデザインの自由度は失われるが

誰でも簡単に目次を追加できるのが売りである。

プラグインのトップページは次

gatsby-remark-table-of-contents | GatsbyJS

公式は英語サイトであり日本語の解説サイトも少ないためこの記事で出来る限りわかりやすく解説する。

インストール

npm i gatsby-remark-table-of-contents

インストール後gatsby-config.jsに追記する

gatsby-config.jsを設定

gatsby-config.js内のgatsby-transformer-remarkの配下にプラグインを追記する。

plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-table-of-contents`,
            options: {
              exclude: "目次",
              tight: false,
              fromHeading: 1,
              toHeading: 6
            },
          }
        ],
      },
    },
  ],

2020/08/27追記:v0.1.0からoptionsclassNameが追加されて目次にクラスを付けられるようになった。

これにより後からスタイリングが出来る...かも?(未確認)

使い方

基本機能だけならこれ以上設定は必要が無いところが楽。

これをインストールしたらmdファイルに次のコードブロックを挿入するだけ。

​```toc
# This code block gets replaced with the TOC
​```

※上は公式コード。#行はコメントのため削除して構わない。

設定が必要なければこれだけで動作するはずである。

設定

gatsby-config.jsに先程追記したプラグインのoptionsを直接設定することで基本動作を設定できる。

exclude

ここに記述したデータと一致する見出しは目次から除外される。

例えば上の設定ではexclude: "目次"となっているので実際の.mdファイルに次のように書いた場合

# 目次

​```toc
# This code block gets replaced with the TOC
​```

「目次」と書いてあるコードは目次に入らなくなる(「目次」という項目そのものを目次にいれてもしかたない)

※ここには正規表現が使えるが難しくなるので解説は省略。詳しくは公式を参照。

fromHeading

このプラグインは#のタグから始まる「見出し」を目次にするというシンプル設計だが

#何個ついている見出しから目次にする?」という設定がこれである。

デフォルト1で基本OKだと思うが「## 見出し の レベル2(h2タグ)」から目次にしたい場合は2にする。

例えばこの記事の上の「設定」という大きな文字は#が1個なのでh1タグになっており

「fromHeading」と書いてある箇所は#が2個でh2タグになる。

ここでfromHeading: 2を設定に書き込んでおくと実際に生成される目次には「設定」という項目は出てこず

「fromHeading」という項目は目次として現れる。

toHeading

こちらは逆に#の個数がどこまでの階層を目次として表示するかである。

1に設定すれば#が1個のh1タグしか目次に設定されない。

※この場合はfromHeadingtoHeading1を記述

こちらも基本的にデフォルト6から設定を変更する必要はないだろう。

数値設定の注意点

fromHeading <= toHeadingであること

つまりfromHeading の設定はtoHeadingの設定と同じか小さい必要がある。

これを反対にしてしまうと記事が表示されなくなるので注意。

記事ごとに設定を変える

先程tocと書いたコードブロック内に設定を入れることで記事ごとに設定を変えることが出来る。

※こちらはgatsby-config.jsに書いた設定より優先度が高くなる

​```toc
# This code block gets replaced with the TOC
exclude: Table of Contents
tight: false,
from-heading: 2
to-heading: 6
​```

さいごに

こちらのプラグインは設定項目が少なく非常に簡単に導入が出来る。

ページ内リンクのプラグインと合わせる必要があるが入れておいて損はないプラグインかと思う。

※ページ内リンクプラグインは次を推奨

gatsby-remark-autolink-headers | GatsbyJS

この記事をシェア:

author icon

仮想トイレ @CrypticToilet
プログラミングや仮想通貨のシステムトレードに関する情報を更新中!どんな情報を流しても詰まらないトイレ。