https://github.com/JS-DevTools/rehype-toc
A rehype plugin that adds a table of contents (TOC) to the page
https://github.com/JS-DevTools/rehype-toc
html html5 javascript nodejs rehype rehype-plugin table-of-contents toc unified
Last synced: 24 days ago
JSON representation
A rehype plugin that adds a table of contents (TOC) to the page
- Host: GitHub
- URL: https://github.com/JS-DevTools/rehype-toc
- Owner: JS-DevTools
- License: mit
- Created: 2019-06-20T11:33:48.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-07-29T17:11:53.000Z (10 months ago)
- Last Synced: 2025-04-18T10:57:26.414Z (about 1 month ago)
- Topics: html, html5, javascript, nodejs, rehype, rehype-plugin, table-of-contents, toc, unified
- Language: JavaScript
- Homepage: https://jstools.dev/rehype-toc/
- Size: 222 KB
- Stars: 76
- Watchers: 2
- Forks: 17
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-rehype - rehype-toc - Add a table of contents (TOC). (Plugins)
README
# Table of Contents plugin for Rehype
A [rehype](https://github.com/rehypejs/rehype) plugin that adds a table of contents (TOC) to the page
[](https://github.com/JS-DevTools/rehype-toc/actions)
[](https://github.com/JS-DevTools/rehype-toc/actions)
[](https://coveralls.io/github/JS-DevTools/rehype-toc)
[](https://david-dm.org/JS-DevTools/rehype-toc)
[](https://www.npmjs.com/package/@jsdevtools/rehype-toc)
[](LICENSE)
[](https://plant.treeware.earth/JS-DevTools/rehype-toc)
Features
--------------------------
- Adds a `` and `
` list outlining all headings on the page
- Combine with [rehype-slug](https://github.com/rehypejs/rehype-slug) to create links to each heading
- Ignores headings outside of `` if it exists
- You can customize which headings are included (defaults to `` - ``)
- You can customize the CSS classes on every TOC element
- Hooks give you complete customization of the generated HTML
Example
--------------------------
**input.html**
Here's the original HTML file. There are three levels of headings (`
` - ``), and none of them have IDs.
```html
Apple Pie Recipe
This is the world's best apple pie recipe...
Filling
The filling is the best part...
Preparing the apples
Cut the apples into 1/4 inch slices...
Preparing the spice mix
In a mixing bowl, combine sugar, cinnamon...
Crust
How to make the perfect flaky crust...
Preparing the dough
Combine flour, sugar, salt...
The criss-cross top
Cut the top crust into 1/2 inch strips...
```
**example.js**
This script reads the `input.html` file above writes the results to `output.html` (shown below). The script uses [unified](https://unifiedjs.com/), [rehype-parse](https://github.com/rehypejs/rehype/tree/master/packages/rehype-parse), [rehype-slug](https://github.com/rehypejs/rehype-slug), and [rehype-stringify](https://github.com/rehypejs/rehype/tree/master/packages/rehype-stringify).
```javascript
const unified = require("unified");
const parse = require("rehype-parse");
const slug = require("rehype-slug");
const toc = require("@jsdevtools/rehype-toc");
const stringify = require("rehype-stringify");
const fs = require("fs");
async function example() {
// Create a Rehype processor with the TOC plugin
const processor = unified()
.use(parse)
.use(slug)
.use(toc)
.use(stringify);
// Read the original HTML file
let inputHTML = await fs.promises.readFile("input.html");
// Process the HTML, adding heading IDs and Table of Contents
let outputHTML = await processor.process(inputHTML);
// Save the new HTML
await fs.promises.writeFile("output.html", outputHTML);
}
```
**output.html**
Here's the HTML that gets created by the above script. Notice that a table of contents has been added at the top of the ``, with links to each of the headings on the page. The headings also now have IDs, thanks to [rehype-slug](https://github.com/rehypejs/rehype-slug).
```html
Apple Pie Recipe
This is the world's best apple pie recipe...
Filling
The filling is the best part...
Preparing the apples
Cut the apples into 1/4 inch slices...
Preparing the spice mix
In a mixing bowl, combine sugar, cinnamon...
Crust
How to make the perfect flaky crust...
Preparing the dough
Combine flour, sugar, salt...
The criss-cross top
Cut the top crust into 1/2 inch strips...
```
Installation
--------------------------
You can install Rehype TOC via [npm](https://docs.npmjs.com/about-npm/).
```bash
npm install @jsdevtools/rehype-toc
```
You'll probably want to install [unified](https://unifiedjs.com/), [rehype-parse](https://github.com/rehypejs/rehype/tree/master/packages/rehype-parse), [rehype-stringify](https://github.com/rehypejs/rehype/tree/master/packages/rehype-stringify), and [rehype-slug](https://github.com/rehypejs/rehype-slug) as well.
```bash
npm install unified rehype-parse rehype-stringify rehype-slug
```
Usage
--------------------------
Using the Rehype TOC plugin requires an understanding of how to use Unified and Rehype. [Here is an excelleng guide](https://unifiedjs.com/learn/guide/introduction-to-unified/) to learn the basics.
The Rehype TOC plugin works just like any other Rehype plugin. Pass it to [the `.use()` method](https://github.com/unifiedjs/unified#processoruseplugin-options), optionally with an [options object](#options).
```javascript
const unified = require("unified");
const toc = require("@jsdevtools/rehype-toc");
// Use the Rehype TOC plugin with its default options
unified().use(toc);
// Use the Rehype TOC plugin with custom options
unified().use(toc, {
headings: ["h1", "h2"], // Only include
and headings in the TOC
cssClasses: {
toc: "page-outline", // Change the CSS class for the TOC
link: "page-link", // Change the CSS class for links in the TOC
}
});
```
Options
--------------------------
The Rehype TOC plugin supports the following options:
|Option |Type |Default |Description
|:---------------------|:-------------------|:----------------------|:-----------------------------------------
|`nav` |boolean |true |Determines whether the table of contents is wrapped in a `` element.
|`position` |string |"afterbegin" |The position at which the table of contents should be inserted, relative to the `` or `` element. Can be "beforebegin", "afterbegin", "beforeend", or "afterend". See [the `insertAdjacentElement()` docs](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentElement) for an explanation of each value.
|`headings` |array of strings |h1, h2, h3, h4, h5, h6 |The HTML heading tags to include in the table of contents
|`cssClasses.toc` |string |toc |The CSS class name for the top-level `` or `
` element that contains the whole table of contents.
|`cssClasses.list` |string |toc-level |The CSS class name for all `` elements in the table of contents, including the top-level one.
|`cssClasses.listItem` |string |toc-item |The CSS class name for all `- ` elements in the table of contents.
|`cssClasses.link` |string |toc-link |The CSS class name for all `` elements in the table of contents.
|`customizeTOC` |function(toc) | |Allows you to customize the table of contents before it is added to the page.
The function receives the TOC node tree and can modify it in any way you want. Or you can return a new node tree to use instead. Or return `false` to prevent the the TOC from being added to the page.
|`customizeTOCItem` |function(toc, heading)| |Allows you to customize each item in the table of contents before it is added to the page.
The function receives the TOC item's node tree and the heading node that it refers to. You can modify the nodes in any way you want. Or you can return a new node tree to use instead. Or return `false` to prevent the the TOC from being added to the page.
Contributing
--------------------------
Contributions, enhancements, and bug-fixes are welcome! [Open an issue](https://github.com/JS-DevTools/rehype-toc/issues) on GitHub and [submit a pull request](https://github.com/JS-DevTools/rehype-toc/pulls).
#### Building
To build the project locally on your computer:
1. __Clone this repo__
`git clone https://github.com/JS-DevTools/rehype-toc.git`
2. __Install dependencies__
`npm install`
3. __Build the code__
`npm run build`
4. __Run the tests__
`npm test`
License
--------------------------
Rehype TOC is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
This package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/JS-DevTools/rehype-toc) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
Big Thanks To
--------------------------
Thanks to these awesome companies for their support of Open Source developers ❤
[](https://travis-ci.com)
[](https://saucelabs.com)
[](https://coveralls.io)