markdown-it-table-of-contents

A table of contents plugin for Markdown-it. Simple, customizable and with a default slugifier that matches that of https://www.npmjs.com/package/markdown-it-anchor (>5.0.0).

Looking for maintainer

I'm looking for someone to take over this package to maintain and improve on it. Interested? Open an issue and just quickly explain your thoughts...

Usage

var MarkdownIt = require("markdown-it");
var md = new MarkdownIt();

md.use(require("markdown-it-anchor").default); // Optional, but makes sense as you really want to link to something
md.use(require("markdown-it-table-of-contents"));

Then add [[toc]] where you want the table of contents to be added in your markdown.

Example markdown

This markdown:

# Heading

[[toc]]

## Sub heading 1
Some nice text

## Sub heading 2
Some even nicer text

... would render this HTML using the default options specified in "usage" above:

<h1 id="heading">Heading</h1>

<div class="table-of-contents">
  <ul>
    <li><a href="#heading">Heading</a>
      <ul>
        <li><a href="#sub-heading-1">Sub heading 1</a></li>
        <li><a href="#sub-heading-2">Sub heading 2</a></li>
      </ul>
    </li>
  </ul>
</div>

<h2 id="sub-heading-1">Sub heading 1</h2>
<p>Some nice text</p>

<h2 id="sub-heading-2">Sub heading 2</h2>
<p>Some even nicer text</p>

Options

You may specify options when useing the plugin. like so:

md.use(require("markdown-it-table-of-contents"), options);

These options are available:

Name | Description | Default -----------------------|-------------------------------------------------------------------------------------|------------------------------------ "includeLevel" | Headings levels to use (2 for h2:s etc) | [1, 2] "containerClass" | The class for the container DIV | "table-of-contents" "slugify" | A custom slugification function | encodeURIComponent(String(s).trim().toLowerCase().replace(/\s+/g, '-')) "markerPattern" | Regex pattern of the marker to be replaced with TOC | /^\[\[toc\]\]/im "listType" | Type of list (ul for unordered, ol for ordered) | ul "format" | A function for formatting headings (see below) | md.renderInline(content) "containerHeaderHtml" | Optional HTML string for container header | <div class="toc-container-header">Contents</div> "containerFooterHtml" | Optional HTML string for container footer | <div class="toc-container-footer">Footer</div> "transformLink" | A function for transforming the TOC links | undefined

format is an optional function for changing how the headings are displayed in the TOC.

By default, TOC headings will be formatted using markdown-it's internal MD formatting rules (i.e. it will be formatted using the same rules / extensions as other markdown in your document). You can override this behavior by specifying a custom format function. The function should accept two arguments:

1. content - The heading test, as a markdown string.
2. md – markdown-it's internal markdown parser object. This should only be need for advanced use cases.

function format(content, md) {
  // manipulate the headings as you like here.
  return manipulatedHeadingString;
}

transformLink is an optional function for transform the link as you like.

function transformLink(link) {
  // transform the link as you like here.
  return transformedLink;
}