auto-toc.js

📖 minimal 1KB on-the-fly TOC generator

Creates a table of contents automatically in your generated markdown or any other HTML page.

Demo

Try the online editor

Why another TOC generator?

Of course there are already tools to generate a TOC, but they need to be executed during build time. If you convert markdown to HTML you need a build process anyway, but generation of a TOC might be another build step in your pipeline, if you don't use Jekyll with Kramdown which suports a TOC out of the box.

This library generates the TOC at runtime in the browser. If you use HTML (not generated from markdown) you can use this library as well. It helps you to avoid updating your TOC at build time completely.

Comparision:

Name	Type	Size (GZIP)
markdown-toc	Buildtime	-
doctoc	Buildtime	-
auto-toc.js	Runtime, minimal	1.2k
contents	Runtime, advanced	23k
TOC	Runtime, jQuery	1.2k + jQuery
jquery.tocify	Runtime, jQuery	2.3k + jQuery
GitHub userscripts	Userscript	2.8k

Usage

---

NOTE This won't work for your README.md files on github.com, see here why.
This feature needs to be provided by GitHub, see here

---

You can use this with README.md files on your GitHub pages or any other pages, where you have control to the (sub)domain.

Your README.md before

# Your fancy library
## Installation
### Windows
### OSX
## Usage
### Basic
### Advanced

Assuming all the headings are children of a div with the class content in your generated HTML file. Then just add a div element with a special class and add two script tags:

# Your fancy library
## Table of contents
<div
  data-toc
  data-toc-max=6
  data-toc-ignore="['Your fancy library', 'Table of contents']"
>
</div>
## Installation
### Windows
### OSX
## Usage
### Basic
### Advanced
<script src="https://cdn.jsdelivr.net/auto-toc.js/1.0.0/dist.js"></script>

API

autoToc(content, placeholderSelector, options)

• content - CSS selector or HTMLElement of the parent of all headings
• placeholderSelector - CSS selector where to inject the TOC
• contentSelector - options object
  • max - Maximum heading level for TOC generation
  • ignore - Array of strings which will be ignored for TOC generation

Embed auto-toc.js

You can either use jsdelivr to embed auto-toc.js (see example above) to your page or install it via npm:

npm i auto-toc --save

auto-toc.js is bundled as Universal Module Defition. So you can use it with CommonJS, AMD or just via the global window scope.

See it in action

• js-joda
  • result
  • setup with GitHub Pages + include external md file

CommonJS

var autoToc = require('auto-toc')

Ignoring headings via CSS class

You can also ignore headings by using the toc-ignore class:

<h2 class="toc-ignore">Ignore this heading in the TOC</h2>