How to create a table of contents to Jekyll blog post?

Question

If I have a page/post in Jekyll with headers, is it possible to auto-generate a table-of-contents/outline for navigation? Something akin to the top matter of a Wikipedia article.

Wivina

Answer 1

That is the markup parser's task.

In case of Markdown one of the syntax extensions defines Automatic generation of the table of contents:

* This will become a table of contents (this text will be scrapped).
{:toc}

This works in Maruku and kramdown.

Neelon

OK, it works but only if there is an H1 header in the markdown file, according to this: webiva.lighthouseapp.com/projects/38599/tickets/… – Greenlaw

Interesting limitation, @jjmerelo. I never hit it. Thanks for the information. – Neelon

I also tried it in kramdown; but the problem was elsewhere: it bailed out with lots of messages if it found a mailto: URL in the text. Other that that, it should work. – Greenlaw

Not working in kramdown 1.3.1, and could not find this option documented at kramdown.gettalong.org – Sofar

@CiroSantilli It's documented here. "Just assign the reference name “toc” to an ordered or unordered list by using an IAL and the list will be replaced with the actual table of contents." Note: it's not sufficient to just place {:toc} where you want the table of contents. {:toc} must be placed immediately after a list item. – Urn

Answer 2

I have TOC for Jekyll blog which looks similar to Wikipedia TOC

So all my Jekyll posts have a Table of Contents section. It can be done just using kramdown.

Use this code inside your post where you want the TOC to appear

* Do not remove this line (it will not be displayed)
{:toc}

And use this CSS to style it like Wikipedia TOC

// Adding 'Contents' headline to the TOC
#markdown-toc::before {
    content: "Contents";
    font-weight: bold;
}


// Using numbers instead of bullets for listing
#markdown-toc ul {
    list-style: decimal;
}

#markdown-toc {
    border: 1px solid #aaa;
    padding: 1.5em;
    list-style: decimal;
    display: inline-block;
}

Use appropriate colors that suit your blog.

That is it!

TOC can also be done with the help of jekyll-table-of-contents, if in any case the above method doesn't work. This one uses Jquery and a js file.

Here is the detailed guide on how I did it: Jekyll TOC

Fou

I have try to do some syntax highlighting but can get it to work. I have pygments install with pip. – Carpel

Is it possible to limit toc generation only from h2 to h4? – Windpipe

Kramdown can be controlled using these options. Look for toc_levels. – Fou

The easiest way I found to control levels of toc in kramdown is to simply turn off specific headers by putting {:.no_toc) in the line below the header you would like to switch off. This is where I found these instructions – Iodide

Answer 3

https://github.com/allejo/jekyll-toc provides very easy way to add TOC to your jekyll page.

1. Download the latest toc.html file (caution! should be raw file)
2. copy this file to _includes folder.
3. add this line before {{content}}: {% include toc.html html=content %}

Chipper

Answer 4

I'm assuming you mean a list of all H1, H2 elements etc in the content itself? I don't think Jekyll has anything built-in to handle that. I suspect the easiest way is to let Javascript generate it for you once the page has rendered, using something like this jQuery plugin, or one of the many other plugins/snippets available.

Inherited

Answer 5

you can use this code before your contents.

<link rel="stylesheet" href="http://yandex.st/highlightjs/6.2/styles/googlecode.min.css">

<script src="http://code.jquery.com/jquery-1.7.2.min.js"></script>
<script src="http://yandex.st/highlightjs/6.2/highlight.min.js"></script>

<script>hljs.initHighlightingOnLoad();</script>
<script type="text/javascript">
 $(document).ready(function(){
      $("h2,h3,h4,h5,h6").each(function(i,item){
        var tag = $(item).get(0).localName;
        $(item).attr("id","wow"+i);
        $("#category").append('<a class="new'+tag+'" href="#wow'+i+'">'+$(this).text()+'</a></br>');
        $(".newh2").css("margin-left",0);
        $(".newh3").css("margin-left",20);
        $(".newh4").css("margin-left",40);
        $(".newh5").css("margin-left",60);
        $(".newh6").css("margin-left",80);
      });
 });
</script>
<div id="category"></div>

Keifer

Answer 6

All these methods specified didn't work for me for the GitHub pages blog, also I wanted to simply use the liquid for the purpose.

Here is the detailed description.

How to add toc in Jekyll blog

Here is how it looks.

Spermary