Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Liquid filter to generate Table of Content into Jeklyll pages
branch: master
Failed to load latest commit information.
_plugins Assign an id to anchor's targets
css First commit
js Collapse toc if cookie is set
.gitignore Initial commit
README.md Update README.md
TOC-Sample.png Added screenshot

README.md

jekyll-toc-generator

Liquid filter to generate Table of Content into Jeklyll pages

This filter adds to jekyll pages a Table of Content (TOC), it generates the necessary HTML code.

Example

The image below shows the result for the markdown page alignRules.md

image

Installation

Prerequisites

To use tocGenerator.rb you need nokogiri

  1. copy the file tocGenerator.rb into the _plugins folder
  2. copy the file css/toc.css to you css site and include into _layouts (this is recommended but not necessary)
  3. finished

How to use

You must replace the {{ content }} directive with {{ content | toc_generate }}

The output contains the HTML code with the TOC and anchor's targets with the id attribute

Example

<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8' />
    <title>{{ page.title }}</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>

Style the TOC table

The TOC must have some CSS style to appear correctly, you can find a default implementation into file css/toc.css The style is compatible with mediawiki themes

Disable generation per page

It is possible to suppress the TOC generation in specific pages, for example the index page normally doesn't have a TOC.
This can be done into the Front Matter section used by jekyll

You must add the noToc: true directive

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

Advanced configuration

Normally no configuration is necessary but you can set some parameter into you _config.yml file

Parameter name Description Default value
minItemsToShowToc Minimum number of items to show the TOC
Suppose you want to generated the TOC only if there are at least 3 H1
0 (no limit)
anchorPrefix The prefix used to generate the anchor name tocAnchor-
showToggleButton The TOC has a button used to collapse/expand the list, this requires a little of Javascript
This package contains a jQuery plugin to handle the click
false

Toggling the button via jQuery

If the toogle button is visible you can use the jquery plugin included in this repository

Below is shown an usage example

<!DOCTYPE html>
<html>
  <head>
    <title>{{ page.title }}</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.tocLight.js"></script>

    <script type="text/javascript">
        $(function() {
          $.toc.clickHideButton();
        });
  </script>

  </head>
  <body id="small">
        {{ content | toc_generate }}
  </body>
</html>

How it works

The filter converts all H1 and H2 elements in a parent-child TOC based on how the markdown code is traslated in HTML. Markdown generates H1 and H2 as siblings

For example the markdown code shown below

heading 1
=========

blah blah 

heading 1.1
-----------

Generates the following HTML code

<h1>heading 1</h1>
<p>blah blah</p>
<h2>heading 1.1</h2>

Github pages can't use plugins

If you host your jekyll pages on github you can't run plugins, in this scenario you can use a full javascript solution using TOC Generator for Markdown

Something went wrong with that request. Please try again.