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.

_config.yml

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"
---

_config.yml

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.

_config.yml

Thank you for your attention.

originally published at https://francopasut.github.io on january 4, 2020.

Comments

Post a Comment

Popular posts from this blog

Vim: Cut, Copy and Paste to and from the system clipboard

Image
Vim: Cut, Copy and Paste to and from the system clipboard Table of Contents 1. Cut, Copy and Paste using the computer keyboard 2. Vim and the clipboard 3. From Vim to the Clipboard 4. From the Clipboard to Vim 5. Some key shortcuts in gVim Figure 1: Vim 1 Cut, Copy and Paste using the computer keyboard Everybody knows how to use the keyboard combinations Ctrl-c , Ctrl-x , and Ctrl-v in Windows and Linux (or Cmd-c , Cmd-x and Cmd-v in macOS) to copy, cut and paste text across applications. Many think that those combinations are universal and work with any application. But Vim and gVim are different, they use another system to exchange information with the rest of the IT world. For example, in Vim under Linux, the key combination Ctrl-v corresponds to the visual block function and does not affect the pasting text. I wrote this article to remind me, as a non-programmer, the key combinations to be used in the Vim world to sha
Read more

Vim: searching for text containing a slash or a question mark

Vim: searching for text containing a slash or a question mark Vim: the search command To activate a text search in Vim, press one of the following trigger keys in your keyboard: the slash "/" key (do not confuse with the back-slash "\" key) the question mark key. By pressing the slash "/" key will activate a forward search. By pressing the question mark "/" key will activate a backward search. To move the cursor to the results in your document, press the "n" key (mnemonic for “ next ”). To invert the direction of the cursor, press the "N" key, (“upper n”) . What about if you need to search for a slash or a question mark , i.e. the same trigger characters , in your document? You can prepend the Escape character to the trigger key. The Escape character The Escape character is the back-slash key: "\" . Just an example: if you need to forward search (then with / trigger k
Read more