37

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.

Jacek Laskowski
  • 72,696
  • 27
  • 242
  • 420
Zando
  • 5,473
  • 8
  • 30
  • 37

6 Answers6

44

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.

boxed
  • 3,895
  • 2
  • 24
  • 26
manatwork
  • 1,689
  • 1
  • 28
  • 31
  • 2
    OK, it works but only if there is an H1 header in the markdown file, according to this: http://webiva.lighthouseapp.com/projects/38599/tickets/5-maruku-table-of-contents-not-generating-without-extra-h1-tag – jjmerelo Jun 29 '13 at 17:46
  • Interesting limitation, @jjmerelo. I never hit it. Thanks for the information. – manatwork Jun 30 '13 at 10:24
  • 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. – jjmerelo Jun 30 '13 at 16:41
  • 1
    Not working in kramdown 1.3.1, and could not find this option documented at http://kramdown.gettalong.org/ – Ciro Santilli OurBigBook.com Feb 16 '14 at 14:46
  • 6
    @CiroSantilli It's documented [here](http://kramdown.gettalong.org/converter/html.html#toc). _"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. – TachyonVortex Jun 29 '14 at 12:45
12

I have TOC for Jekyll blog which looks similar to Wikipedia TOC enter image description here

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

Sharath kumar
  • 1,118
  • 13
  • 17
  • I have try to do some syntax highlighting but can get it to work. I have pygments install with `pip`. – redeemefy Jun 14 '17 at 21:59
  • Is it possible to limit toc generation only from h2 to h4? – lordparthurnaax Oct 07 '20 at 13:49
  • Kramdown can be controlled using these [options](https://kramdown.gettalong.org/options.html). Look for ``toc_levels``. – Sharath kumar Apr 28 '21 at 06:54
  • 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](https://dieghernan.github.io/chulapa-101/cheatsheets/02-kramdown-cheat-sheet) – Stackstudent_09 Jul 12 '22 at 17:59
2

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 %}
greentec
  • 2,130
  • 1
  • 19
  • 16
1

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>
xiaoyu2er
  • 707
  • 8
  • 7
1

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.

Jon M
  • 11,669
  • 3
  • 41
  • 47
0

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.

Jekyll toc

ranvir
  • 106
  • 1
  • 7