at
auto-toc
npm i auto-toc
at

auto-toc

πŸ“– minimal 1KB on-the-fly TOC generator for markdown and HTML

by Anton W

0.0.6 (see all)License:ISCTypeScript:Not Found
npm i auto-toc
Readme

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:

NameTypeSize, gzip
markdown-tocBuildtime-
doctocBuildtime-
auto-toc.jsRuntime, minimal1.0k
contentsRuntime, advanced23k
TOCRuntime, jQuery1.2k + jQuery
jquery.tocifyRuntime, jQuery2.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

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>

Downloads/wk

2

GitHub Stars

14

LAST COMMIT

7yrs ago

MAINTAINERS

1

CONTRIBUTORS

1

OPEN ISSUES

1

OPEN PRs

1
VersionTagPublished
0.0.6
latest
7yrs ago
No alternatives found
No tutorials found
Add a tutorial
No dependencies found

Rate & Review

100
No reviews found
Be the first to rate