R note

GatsbyでMarkdownの見出しに自動でidを入れるプラグイン

2019年1月12日2019年1月13日

GatsbyJS

Markdownで書いた記事の見出し要素（h1、h2、h3など）にidを入れてくれるgatsby-remark-autolink-headersプラグインを入れました。これで、長い記事でも目次（Table of Contents = TOC）を入れてページ内にリンクができます。

目次

プラグイン導入前

プラグインを入れないと、以下のように見出し要素はそのままHTMLに変換されるだけですが...

Markdown

## H2見出し要素
### H3見出し要素

HTML

<h2>H2見出し要素</h2>
<h3>H3見出し要素</h3>

プラグイン導入後

gatsby-remark-autolink-headersを入れると以下のようにHTMLへの変換の際にid属性を入れてくれるようになりなす。idには見出しテキストがそのまま入るので、日本語の見出しは日本語でidが入ります（これって問題ないんだっけ？）。

HTML

<h2 id="H2見出し要素">H2見出し要素</h2>
<h3 id="H3見出し要素">H3見出し要素</h3>

見出しがダブっていても大丈夫？

試しに同じ見出しを2つ入れてみたら以下のように処理されてました。ちゃんと考慮されてました！

Markdown

## 見出しだよ
## 見出しだよ

書き出されるHTML

<h2 id="見出しだよ">見出しだよ</h2>
<h2 id="見出しだよ-1">見出しだよ</h2>

導入方法

導入は簡単です。プラグインをnpmでインストールしてgatsby-config.jsのプラグイン一覧に記入するだけです。

npmでインストール

npm i -S gatsby-remark-autolink-headers

gatsby-config.jsに記入

プラグイン一覧にgatsby-remark-autolink-headersを追加します。以下のようにgatsby-transformer-remarkのオプションとして記入します。あと、gatsby-remark-prismjsよりも前に記入する必要があります。

    { resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-external-links`,
            options: {
              rel: "noopener noreferrer",
            }
          },
          {            resolve: `gatsby-remark-autolink-headers`,            options: {              offsetY: `30`,              icon: false,              className: `custom-class`,              maintainCase: true,            },          },          {
            resolve: `gatsby-remark-prismjs`,
          }
        ]
      }

PrismJSを使っている場合の注意点

上にも書きましたが、1つ注意点があって、PrismJS（gatsby-remark-prismjs）を使っている場合は、先にgatsby-remark-autolink-headersを記入する必要があります。

設定オプション

以下の4つが設定できます。

offsetY

リンクをクリックして移動した時の見出しの上の空き（オフセット）。ここで指定した分だけ上に空きができます。

icon

デフォルトだと見出しにhoverすると左側にリンク・アイコンが表示されます。この画像のカスタマイズや非表示設定ができます。テンプレートリテラルに入れたSVGまたはfalseで非表示に。

className

アンカーにカスタムのクラス名を入れるオプションと書いてあるんですが、なんのことか不明です。なんだろう？

maintainCase

idに使う文字列は見出しから引っ張ってこられる仕様ですが、その際に見出しの大文字・小文字を保持するかを決めるオプション。trueまたはfalse。例えば、falseにするとFLOCSSという見出しではid="flocss"になります。

見出しには英語を使うこともあると思うのでtureにしておいたほうが良さそうです。

一覧に戻る