目次を追加したい

Gatsby.jsにてマークダウンで書かれた記事の中で目次を追加するプラグインを紹介する。

2022/06/01:本サイトは右ドロワに目次を表示する改修を行ったためこちらのプラグインは現在使用していない。

アップデート情報

2022/03/06

2.0.0が公開されていたのでアップグレードを行った。

公式Githubではまだ詳細のアナウンスなし。Gatsby.js v4の対応か？

アップデート後問題なく動作していることを確認。

signalwerk/gatsby-remark-table-of-contents: gatsby remark plugin to generate table of contents

※基本の使い方は以前と変わりないのでこのまま読んでもらえればと思う。

前提条件

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

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

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

gatsby-remark-autolink-headers | GatsbyJS

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

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

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からoptionsにclassNameが追加されて目次にクラスを付けられるようになった。

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

使い方

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

これをインストールしたら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タグしか目次に設定されない。

※この場合はfromHeadingもtoHeadingも1を記述

こちらも基本的にデフォルト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