# @takanorip/markdown-it-table-of-contents

> A Markdown-it plugin for adding a table of contents to markdown documents

Latest version **0.5.2** (published 2021-02-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @takanorip/markdown-it-table-of-contents
pnpm add @takanorip/markdown-it-table-of-contents
yarn add @takanorip/markdown-it-table-of-contents
bun add @takanorip/markdown-it-table-of-contents
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.5.2 |
| Published | 2021-02-01 |
| First published | 2020-07-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >6.4.0 |
| Dependencies | 0 |
| Unpacked size | 20.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 111 |
| Author | Martin Lissmyr |
| Maintainers | takanorip |
| Keywords | markdown, markdown-it, toc, table of contents, markdown-it-plugin |

## Links

- npm: https://www.npmjs.com/package/@takanorip/markdown-it-table-of-contents
- Repository: https://github.com/martinlissmyr/markdown-it-table-of-contents
- Issues: https://github.com/martinlissmyr/markdown-it-table-of-contents/issues
- npm.io page: https://npm.io/package/@takanorip/markdown-it-table-of-contents

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 0.5.2 (latest) — 2021-02-01
- 0.0.1 — 2020-07-07

## README

# 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

``` javascript
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:
``` 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:
``` html
<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 `use`ing the plugin. like so:
``` javascript
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.

```js
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.
```js
function transformLink(link) {
  // transform the link as you like here.
  return transformedLink;
}
```

---
_Source: https://npm.io/package/@takanorip/markdown-it-table-of-contents · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._