A rehype plugin that adds a table of contents (TOC) to the page
npm install rehype-toc
Features
--------------------------
- Adds a and
- Combine with 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.
`` This is the world's best apple pie recipe...html
Apple Pie Recipe
The filling is the best part...
Cut the apples into 1/4 inch slices...
In a mixing bowl, combine sugar, cinnamon...
How to make the perfect flaky crust...
Combine flour, sugar, salt...
Cut the top crust into 1/2 inch strips...
example.js
This script reads the
file above writes the results to output.html (shown below). The script uses unified, rehype-parse, rehype-slug, and 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.`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.
bash
npm install @jsdevtools/rehype-toc
`You'll probably want to install unified, rehype-parse, rehype-stringify, and 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 to learn the basics.
The Rehype TOC plugin works just like any other Rehype plugin. Pass it to the
method, optionally with an options object.`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
|:---------------------|:-------------------|:----------------------|:-----------------------------------------
|
|boolean |true |Determines whether the table of contents is wrapped in a