Table Of Contents (TOC), from Org-Mode to Jekyll

What’s a Table Of Contents and why using it?

A Table Of Contents (“TOC”) is an index of a document’s content.

In the world wide web environment it’s usually a list of chapter and sub-chapter headings in the online articles.

Why using it? Obviously: the TOC can give you an overview of the documents’ structure, so you can quickly jump where you’re interested, without spending time reading the rest of the document.

As a not-developer writer in GitHub of some posts, I’d like a simple and fast system to get the TOC of my articles.

Emacs Org-Mode and the autogenerated TOC

An excellent resource to generate a TOC is offered by Emacs with its extraordinary Org-Mode: if you write structured documents in Org-Mode you can easily export it in Markdown (C-c C-c m m, but you must previously customize Emacs with the command org-export-backends and enable the markdown backend) or HTML (C-c C-e h h) and getting an autogenerated TOC based on the document’s headers fully functional in any environment.

In the following image you can see an article of mine with a TOC generated by Org-Mode. By clicking on the image you will be sent to the source of the article.

By the way: try Org-Mode and you will enjoy it!

However, the limitation of this system is that the TOC generated by Org-Mode always appears at the beginning of the article and is not, therefore, dynamically moved while reading it in your browser.

Minimal-Mistakes over Jekyll provides an automatic TOC

When I discovered the theme Minimal-Mistakes for Jekyll I found a very quick way to get the TOC of articles published in GitHub.

For automatic TOC use the following configuration in the Front Matter (the icon is optional):

---
toc: true
toc_label: "My Table of Contents"
toc_icon: "cog"
---

You can also use the /sticky/ version by adding toc_sticky: true in the Front Matter:

---
toc: true
toc_sticky: true
toc_label: "My Table of Contents"
---

The index will be at the top of the page on small format devices, such as smartphones, and on the left persistent on large display devices, such as tablets (in landscape mode) and computer monitors.

Scrolling the page causes the current zone to be highlighted in the TOC.

Thank you for your attention.