auto-toc.js

:book: 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.0k | | contents | Runtime, advanced | 23k | | TOC | Runtime, jQuery | 1.2k + jQuery | | jquery.tocify | Runtime, jQuery | 2.3k + jQuery |

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

# My 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:

# My fancy library
## Table of contents
<div class="toc-placeholder"></div>
## Installation
### Windows
### OSX
## Usage
### Basic
### Advanced
<script src="https://cdn.jsdelivr.net/auto-toc.js/0.0.6/dist.js"></script>
<script>
  autoToc('.content', '.toc-placeholder');
</script>

API

autoToc(contentSelector, placeholderSelector, options)

• contentSelector - CSS selector 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>