Jekyllで作成したサイトでは、Markdownを使って簡単にページ内の目次を 自動生成できます。

現在、使用しているプラグインの各バージョンは下記のとおりです。

  • jekyll (4.1.1)
  • kramdown (2.3.0)

Jekyllではページ内にMarkdownを記載することで目次を自動生成できますが、 これはJekyllのデフォルトMarkdownレンダラーであるkaramdownの機能1です。

例えば、下記のようなMarkdownがあると

* TOC
{:toc}

# Header1

## Header2

ページ内の見出しを収集して、順序のないリスト(<ul>)を使った 目次を自動的に生成してくれます。

<ul id="markdown-toc">
  <li>
    <a href="#header1" id="markdown-toc-header1">Header1</a>
    <ul>
      <li><a href="#header2" id="markdown-toc-header2">Header2</a></li>
    </ul>
  </li>
</ul>

<h1 id="header1">Header1</h1>

<h2 id="header2">Header2</h2>

下記でも同じように、順序のないリストを使った目次が生成されます。

- TOC
{:toc}

下記のようにすると、順序のあるリスト(<ol>)を使った目次が生成されます。

1. TOC
{:toc}

TOCはどのような文字列でもよく、空でもよいようです (ただし半角スペースは必要です)

<details>2 と組み合わせることで、折り畳み可能な目次も生成できます。

<details open markdown="block">
  <summary>Table of Contents</summary>
- TOC
{:toc}
</details>

特定の見出しを目次から除外したい場合は、見出しの次行に{:.no_toc}と記載します。

* TOC
{:toc}

# Header1

## Header2
{:.no_toc}

レイアウトテンプレート(_layout/*)への記載では動作しないため、 目次を生成したい全てのページへの記載が必要になりますが、 Jekyllのプラグイン3を使うとテンプレートに記載できます。

  1. HTML Converter ¦ karamdown ↩

  2. <details>: 詳細折りたたみ要素(MDN web docs) ↩

  3. jekyll-tocなど ↩