Jekyll製ブログの各見出しに自動アンカー生成を導入する

QiitaやGitHubのマークダウンって、各見出しに自動的にアンカーがついていて、すぐにその見出しのリンク取得できるから便利ですよね。
あれをJekyllで導入する方法を調査して、よいものを見つけたので早速導入してみました。

調査したきっかけ #

自分はとあるエンジニアのコミュニティに参加しています。
そのコミュニティを立ち上げられた方をTwitterでフォローさせていただいているのですが、あるときその方が「Jekyllで見出しにアンカーリンクを自動で付与する方法はないか?」というつぶやきをされていました。

最初は目次から見出しに飛べるようにするのかな?と思ってやりとりをしたのですが、そこでQiitaやGitHubの見出しの話になりました。
QiitaやGitHubのマークダウンの見出しって、自動的に自己要素へのリンクになっていて、すぐにその見出しのリンクが取得できるんですよね。
あれってどうやってるんだろうと。

そこで何かプラグイン等がないか調査してみることにしました。
何か見つかれば当ブログにも導入できるなと。

jekyll-anchor-headings #

調査したところ、こちらのリポジトリを見つけました。
GitHub - jekyll-anchor-headings

概要 #

・READMEの冒頭

GitHub Pages can’t run custom Jekyll plug-ins so when generating anchors for your headings (i.e. h1 - h6), you’re stuck with JavaScript solutions that will inject anchors. But what if your users don’t have JavaScript enabled on their browsers? If you’re building a static website, why not make your anchors static as well?

簡単に静的サイトが構築できるGitHub PagesでもJekyllが使われているのですが、あちらはプラグインが使用できないという制約があります。
そこでJavaScriptで見出しをカスタマイズするという選択肢が出ますが、JavaScriptが無効化されていると、利用することができません。
静的サイトでは、アンカーも静的にしましょうといったことが書いてありました。

・リポジトリの説明

A GitHub Pages compatible way of adding anchors to your headings without a plug-in or JavaScript

こちらに書いてあるとおり、プラグインやJavaScriptを使わずとも、このスニペットを使えば、見出しに自動的にアンカーを付与できますよとのことです。
プラグインでないのでGitHub Pagesでも問題なく使用することができます。

導入実績 #

こちらもREADMEに記述がありました。
比較的有名なサービスやOSSのドキュメントに使われているそうです。
すごいですね!

  • Travis CI Docs (fixed in #1960)
  • Bitrise’s Documentation
  • di’s personal website
  • sitespeed.io
  • Duality’s developer docs
  • Australia’s Vote Flux campaign
  • mlpack.org
  • Riot.js website
  • “Just the Docs” Jekyll theme
  • Microsoft’s TypeScript website
  • VMWare’s Octant documentation

導入方法 #

導入はとても簡単です。

  1. リポジトリから最新のanchor_headings.htmlファイルをダウンロードする

  2. ダウンロードしたファイルを、自ブログコードの_includes配下に格納

  3. レイアウトファイルで{{ content }}のところを以下のように置き換える

{% include anchor-headings.html html=content %}

自分は_layouts/default.htmlの該当箇所を置き換えました。
他のレイアウトファイルもこのレイアウトファイルをベースにしているので、まとめて適用することができました。

オプション #

include文にオプションを渡すことができます。

一例

  • beforeHeading
    見出しの文字の前にアンカーを生成するかどうか(boolで指定、デフォルトはfalse)
  • anchorBody
    アンカー内に配置するコンテンツ(stringで指定、デフォルトは’‘)
    文字列で指定ですが、HTMLのiタグで指定もできました。
  • anchorClass
    アンカーに指定するクラス(stringで指定、デフォルトは’‘)
    このクラスにCSSをあてて、カスタマイズもできます。

詳しくはリポジトリのREADMEでご確認ください。

自分の場合は以下のようにしました。

{% include anchor-headings.html html=content anchorBody='#' anchorClass='anchor-heading' %}

とても簡単に見出しに自動アンカーを導入することができました!
Jekyllを利用している方はぜひ導入してみてはどうでしょうか。

READMEを読んでて気づいたのですが、この製作者の方は、以前目次導入の調査をしていた時に見つけた、jekyll-tocを作った方でもあったそうです。
jekyll-tocに関しても、同様に導入することができ、GitHub Pagesでも使えるようになっていました。

こういう便利なものを作れる方ってすごいですね!
自分もいつか挑戦してみようかどうか…。


遅ればせながら、あけましておめでとうございます。
今年も少しずつブログ書いていきますので、どうぞよろしくお願い致します。

参考リンクまとめ #