Table of contents using Jekyll and Kramdown

Question

I'm trying to use Kramdown's auto "Table of Contents" generator on a page (not a post) on my Jekyll site.

_includes/toc.html

<nav>
  <h4>Table of Contents</h4>
  {:toc}
</nav>

my_cool_stuff/my_cool_page.md

---
layout: page
---

{% include toc.html %}

# The title of my page
## The Subtitle of my page

The HTML is generated literally and I'm not getting a list of headers.

<nav>
  <h4 class="toc_title">On This Page</h4>
  {:toc}
</nav>

What am I setting up wrong?

Answer 1

{:toc} is kramdown tag for automatic Table of content generation.

In your case, you need two more things to make it work :

1. Allow kramdown to parse inside html blocks : in _config.yml add :

   kramdown:
     parse_block_html: true
   

2. in _includes/toc.html, you need to provide a seed list :

   <nav>
     <h4>Table of Contents</h4>
     * this unordered seed list will be replaced by toc as unordered list
     {:toc}
   </nav>
   

Answer 2

I wanted to do something similar but was trying to avoid having any kind of markup in my post page, similar to your {% include toc.html %}.

I found this great Ruby Gem - jekyll-toc that allows you to place a TOC anywhere in a layout file. You enable it in the front matter.