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.
![Chat](https://img.shields.io/badge/chat-discussions-success.svg)
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
Generate a table of contents.
- 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
- Links from the table of contents to following headings, using the same slugs
as GitHub
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
All options are passed to mdast-util-toc
, with the exception that
heading
defaults to 'toc|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.
Related
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, organization, or community you agree to
abide by its terms.
License
MIT © Titus Wormer