unified

Project: remarkjs/remark-toc

Package: remark-toc@7.0.0

  1. Dependencies: 2·Dependents: 65
  2. remark plugin to generate a Table of Contents (TOC)
  1. remark 189
  2. unified 146
  3. plugin 130
  4. markdown 111
  5. mdast 72
  6. text 17
  7. content 16
  8. table 6
  9. plain 4
  10. toc 3
  11. of 2
  12. contents 2
  13. generation 2

remark-toc

Build Coverage Downloads Size Sponsors Backers Chat

remark plugin to generate a Table of Contents.

Install

npm:

npm install remark-toc

Use

Say we have the following file, example.md:

# Alpha

## Table of Contents

## Bravo

### Charlie

## Delta

And our script, example.js, looks as follows:

var vfile = require('to-vfile')
var remark = require('remark')
var toc = require('remark-toc')

remark()
  .use(toc)
  .process(vfile.readSync('example.md'), function(err, file) {
    if (err) throw err
    console.log(String(file))
  })

Now, running node example yields:

# Alpha

## Table of Contents

-   [Bravo](#bravo)

    -   [Charlie](#charlie)

-   [Delta](#delta)

## Bravo

### Charlie

## Delta

API

remark().use(toc[, options])

Generate a Table of Contents.

Note: if you’re later compiling to HTML, you still need to add anchors to headings. Previously that was done by this plugin as well, but now you must .use(slug) to include remark-slug explicitly.

options
options.heading

string?, default: 'toc|table[ -]of[ -]contents?' — Heading to look for, wrapped in new RegExp('^(' + value + ')$', 'i').

options.maxDepth

number?, default: 6 — Maximum heading depth to include in the table of contents, This is inclusive, thus, when set to 3, level three headings, are included (those with three hashes, ###).

options.tight

boolean?, default: false — Whether to compile list-items tightly.

options.skip

string? — Headings to skip, wrapped in new RegExp('^(' + value + ')$', 'i'). Any heading matching this expression will not be present in the table of contents.

Security

Use of remark-toc involves user content and changes the tree, so it can open you up for a cross-site scripting (XSS) attack.

Existing nodes are copied into the table of contents. The following example shows how an existing script is copied into the table of contents.

The following Markdown:

# Table of Contents

## Bravo<script>alert(1)</script>

## Charlie

Yields:

# Table of Contents

-   [Bravo<script>alert(1)</script>](#bravoscriptalert1script)
-   [Charlie](#charlie)

## Bravo<script>alert(1)</script>

## Charlie

This may become a problem if the Markdown is later transformed to rehype (hast) or opened in an unsafe Markdown viewer.

Contribute

See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

This project has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.

License

MIT © Titus Wormer