remark-toc

What is remark-toc?

The remark-toc package is a plugin for the remark markdown processor that automatically generates a table of contents (TOC) for markdown documents. It scans the document for headings and creates a TOC based on those headings, which can be customized and inserted at a specified location in the document.

What are remark-toc's main functionalities?

Generate TOC

This feature allows you to generate a table of contents for a markdown document. The code sample demonstrates how to use the remark-toc plugin with the remark processor to automatically generate a TOC based on the headings in the document.

const remark = require('remark');
const toc = require('remark-toc');

remark()
  .use(toc)
  .process('# Title\n## Subtitle\n### Subsubtitle', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Custom TOC Heading

This feature allows you to customize the heading of the generated TOC. The code sample shows how to set a custom heading 'Table of Contents' for the TOC.

const remark = require('remark');
const toc = require('remark-toc');

remark()
  .use(toc, { heading: 'Table of Contents' })
  .process('# Title\n## Subtitle\n### Subsubtitle', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Custom TOC Depth

This feature allows you to limit the depth of the TOC. The code sample demonstrates how to generate a TOC that includes only headings up to the second level.

const remark = require('remark');
const toc = require('remark-toc');

remark()
  .use(toc, { maxDepth: 2 })
  .process('# Title\n## Subtitle\n### Subsubtitle', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Other packages similar to remark-toc

markdown-toc

The markdown-toc package generates a table of contents for markdown files. It is a standalone tool that can be used via the command line or as a library in Node.js. Unlike remark-toc, which is a plugin for the remark processor, markdown-toc is a more general-purpose tool that can be used independently of any specific markdown processor.

doctoc

The doctoc package is a command-line tool that generates a table of contents for markdown files. It is designed to be used as a standalone tool and can automatically update the TOC in place. Compared to remark-toc, doctoc is more focused on being a CLI tool and does not integrate directly with the remark processor.

README

remark-toc

Generate a Table of Contents in remark.

Installation

npm:

npm install remark-toc

remark-toc is also available as an AMD, CommonJS, and globals module, uncompressed and compressed.

Usage

Dependencies:

var remark = require('remark');
var toc = require('remark-toc');

Process:

var file = remark().use(toc).process([
  '# Alpha',
  '',
  '## Table of Contents',
  '',
  '## Bravo',
  '',
  '### Charlie',
  '',
  '## Delta',
  ''
].join('\n'));

Yields:

# Alpha

## Table of Contents

-   [Bravo](#bravo)

    -   [Charlie](#charlie)

-   [Delta](#delta)

## Bravo

### Charlie

## Delta

API

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

Add a Table of Contents to a Markdown document.

• Looks for the first heading containing "Table of Contents", "toc", or table-of-contents (case insensitive, supports alt/title attributes for links and images too);
• Removes all following contents until an equal or higher heading is found;
• Inserts a list representation of the hierarchy of following headings;
• Adds links to following headings, using the same slugs as GitHub.

options

• heading (string?, default: "toc|table[ -]of[ -]contents?") — Heading to look for, wrapped in new RegExp('^(' + value + ')$', 'i');;
• 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, ###);
• tight (boolean?, default: false) — Whether to compile list-items tightly.

License

MIT © Titus Wormer