remarkjs / Remark Toc
Programming Languages
Projects that are alternatives of or similar to Remark Toc
remark-toc
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.
- 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 includeremark-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
-
remark-slug
– Add anchors to headings using GitHub’s algorithm -
remark-collapse
– Make a section collapsible -
remark-normalize-headings
— Make sure there is no more than a single top-level heading in the document and rewrite the rest accordingly -
remark-behead
— Change header levels -
mdast-util-toc
— Core functionality of this plugin
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.