Table of Contents in Markdown, using only the standard / out of the box Github Pages tooling?

Question

Trying to setup up a blog / documentation using purely hosted / "out of the box" GitHub Pages Jekyll; I am specifically trying to avoid having to run Jekyll locally (although I can).

I have tried http://www.seanbuscay.com/blog/jekyll-toc-markdown/ but that doesn't work.

Is this possible, or does it truly require additional tooling?

marcanuy marcanuy · Accepted Answer · 2018-01-03T13:43:01

By default Jekyll uses Kramdown, it already comes with a TOC generator. You don't need a plugin for this so it will work with github-pages.

kramdown supports the automatic generation of the table of contents of all headers that have an ID set. 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, rendered as nested unordered lists if “toc” was applied to an unordered list or else as nested ordered lists. All attributes applied to the original list will also be applied to the generated TOC list and it will get an ID of markdown-toc if no ID was set.

# Contents
{:.no_toc}

* Will be replaced with the ToC, excluding the "Contents" header
{:toc}

# H1 header

## H2 header

That will give you:

  <h1 class="no_toc" id="contents">Contents</h1>

<ul id="markdown-toc">
  <li><a href="#h1-header" id="markdown-toc-h1-header">H1 header</a>    <ul>
      <li><a href="#h2-header" id="markdown-toc-h2-header">H2 header</a></li>
    </ul>
  </li>
</ul>

<h1 id="h1-header">H1 header</h1>

<h2 id="h2-header">H2 header</h2>

https://kramdown.gettalong.org/converter/html.html#toc

Table of Contents in Markdown, using only the standard / out of the box Github Pages tooling?

1 Answers