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
導入方法 #
導入はとても簡単です。
-
リポジトリから最新の
anchor_headings.htmlファイルをダウンロードする -
ダウンロードしたファイルを、自ブログコードの
_includes配下に格納 -
レイアウトファイルで
{{ 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でも使えるようになっていました。
こういう便利なものを作れる方ってすごいですね！
自分もいつか挑戦してみようかどうか…。
遅ればせながら、あけましておめでとうございます。
今年も少しずつブログ書いていきますので、どうぞよろしくお願い致します。
