Jump to the content

Jekyllの記事に目次を追加する「jekyll-toc-generator」

Jekyll

    Jekyllの記事に目次を追加する「jekyll-toc-generator」

    ブログで技術記事やリファレンスのまとめ・チュートリアルを記事にすると、ページが長くなりがちで情報にたどり着くのが遅くなる。
    このブログの例ではSassの関数リファレンスなどでページコンテンツがかなり長くなった時があった。
    これを見やすくするために記事に目次を設置したい。
    そんな要望にもJekyllはプラグインの追加で対応可能だ。

    jekyll-toc-generator

    今日紹介するのは jekyll-toc-generator だ。

    このプラグインは記事の見出しから目次を追加して目次を生成する。 見出しは {{ content }} の中から抽出してくれる。

    Table Of Contents

    • 目次のCSSは自由に変更可能。
    • 目次の折りたたみを追加することも可能。
    • jekyll-toc-generator では外部ライブラリのnokogiriが必要。一緒にGemをインストールしないと動作しない。

    といった特徴がある。

    導入方法

    nokogiriをインストール

    まず始めに nokogiri をインストールする。

    gem install nokogiri
    # もしくはbundlerの場合、Gemfileに次を追記
    gem 'nokogiri'
    

    ファイルを配置

    1. リポジトリのファイルをダウンロード。
    2. tocGenerator.rb_plugins フォルダにコピーする。
    3. css/toc.css をコピーしてHTMLで読み込む。

    出力設定

    トップレベルの{{ content }}{{ content | toc_generate }} に変更。

    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8" />
        <title>Jekyllの記事に目次を追加する「jekyll-toc-generator」</title>
        <!-- This css contains the default style for TOC -->
        <link rel="stylesheet" type="text/css" media="screen" href="css/toc.css">
      </head>
      <body>
        <div>
            {{ content | toc_generate }}
        </div>
      </body>
    </html>
    

    よし、これでいい。
    基本的な導入はこれでOKだ。

    オプション

    jekyll-toc-generator では各オプション設定ができる。

    CSSの変更

    目次のCSSの変更は css/toc.css を変更する。
    デフォルトはMediaWikiのテーマのものをそのまま持ってきたという感じだ。

    表示設定

    このプラグインではデフォルトで目次の表示がされる。 YAML Front MatterでnoToc: true とすることで、そのページの目次を非表示にできる。

    ---
    permalink: index.html
    layout: default
    title: Main Page with TOC
    noToc: true
    ---
    

    ※この仕様がすごく嫌だったので、後で説明する方法で変更した。

    _config.yml

    ParameterDescriptionDefault
    minItemsToShowToc目次の項目を表示する最小数0
    tocTopTag目次の項目となる見出しの要素。h1〜h5まで指定可能。h1
    anchorPrefix見出し要素のID属性に付与する接頭辞tocAnchor-
    showToggleButtonトグルボタンの表示非表示false

    トグルボタン

    トグルボタンを追加する場合は、_config.ymlshowToggleButton: true を設定後に、js/jquery.tocLight.js をコピーして以下のようにjQuery、jquery-cookie と、コピーしたファイルを読み込む。 さらに$.toc.clickHideButton()Document readyで実行する。

    <!DOCTYPE html>
    <html>
      <head>
        <title>Jekyllの記事に目次を追加する「jekyll-toc-generator」</title>
        <!-- This css contains the default style for TOC -->
        <link rel="stylesheet" type="text/css" media="screen" href="css/toc.css">
    
        <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
        <script src="js/jquery.cookie.js"></script>
        <script src="js/jquery.tocLight.js"></script>
    
        <script type="text/javascript">
            $(function() {
              $.toc.clickHideButton();
            });
      </script>
    
      </head>
      <body id="small">
        {{ content | toc_generate }}
      </body>
    </html>
    

    ぼくはForkして機能を追加した

    jekyll-toc-generator を使ってみたんだけど、ぼくのブログとは仕様上マッチしていない部分があったので、プラグインを少し書き換えた。

    修正した内容は次のとおり。

    • デフォルトで目次を表示しない。YAML Front Matterで表示設定できるようにした。
    • XPATHでのDOM走査方法を変更。h1h2 が兄弟要素でなくとも検出可能にした。
    • _config.yml でのオプション設定を追加。目次の挿入位置を指定できるようにした。追加したのは次の3つ。
     # 目次を挿入する基準となるHTML要素をCSSセレクタで指定する。defaultは'article'。
    tocInsertElement: 'article'
    
    # 目次の挿入位置。tocInsertElementの前か後の位置を選べる。'before' or 'after'。defaultは'before'
    tocInsertPosition: 'before'
    
    # tocInsertElementの子要素に挿入するか。true or false。defaultはfalse
    tocInsertChildren: false
    

    インストール〜導入方法までは同じ。 _config.yml に目次を挿入したい位置を指定する。

    ぼくは記事の始めのh2 の見出しの直前に挿入したかったので、tocInsertElement: .mod-article-body h2:first-of-type とした。

    # toc
    tocTopTag: 'h2'
    anchorPrefix: 'anchor'
    showToggleButton: true
    tocInsertElement: '.mod-article-body h2:first-of-type'
    tocInsertPosition: 'before'
    tocInsertChildren: false
    

    また、デフォルトでは目次は出力されず、出力するには出力したい記事のYAML Front Matter でtoc: true を設定する。

    ---
    layout: posts
    title: post title
    categories: [category]
    toc: true
    ---
    

    かなり自由に挿入位置や表示設定をできるので便利だと思う。

    まとめ

    • jekyll-toc-generator で目次を表示できる。
    • nokogiriを忘れるな。
    • ぼくがForkしたリポジトリのほうが使いやすいから使って欲しい。yuhiisk/jekyll-toc-generator

    ブログに目次を追加して、Qiitaの記事みたいにものすごく読みやすくなったので、 ぜひ導入してみてほしい。

    注目記事

    最近の記事

    ぼくが書いてます

    フロントエンドエンジニア

    イソップ

    ページの先頭に戻る

    Search results

    ×