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.
Generate a Table of Contents in remark.
Installation
npm:
npm install remark-toc
Usage
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
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.
Related
Contribute
See contribute.md
in remarkjs/remark
for ways to get started.
This organisation has a Code of Conduct. By interacting with this
repository, organisation, or community you agree to abide by its terms.
License
MIT © Titus Wormer