rehype-toc
Advanced tools
A rehype plugin that adds a table of contents (TOC) to the page
<nav> and <ol> list outlining all headings on the page<main> if it exists<h1> - <h6>)input.html
Here's the original HTML file. There are three levels of headings (<h1> - <h3>), and none of them have IDs.
<html>
<body>
<h1>Apple Pie Recipe</h1>
<p>This is the world's best apple pie recipe...</p>
<div>
<h2>Filling</h2>
<p>The filling is the best part...</p>
<h3>Preparing the apples</h3>
<p>Cut the apples into 1/4 inch slices...</p>
<h3>Preparing the spice mix</h3>
<p>In a mixing bowl, combine sugar, cinnamon...</p>
</div>
<div>
<h2>Crust</h2>
<p>How to make the perfect flaky crust...</p>
<h3>Preparing the dough</h3>
<p>Combine flour, sugar, salt...</p>
<h3>The criss-cross top</h3>
<p>Cut the top crust into 1/2 inch strips...</p>
</div>
</body>
</html>
example.js
This script reads the input.html file above writes the results to output.html (shown below). The script uses unified, rehype-parse, rehype-slug, and rehype-stringify.
const unified = require("unified");
const parse = require("rehype-parse");
const slug = require("rehype-slug");
const toc = require("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 <body>, with links to each of the headings on the page. The headings also now have IDs, thanks to rehype-slug.
<html>
<body>
<nav class="toc">
<ol class="toc-level toc-level-1">
<li class="toc-item toc-item-h1">
<a class="toc-link toc-link-h1" href="#apple-pie-recipe">
Apple Pie Recipe
</a>
<ol class="toc-level toc-level-2">
<li class="toc-item toc-item-h2">
<a class="toc-link toc-link-h2" href="#filling">
Filling
</a>
<ol class="toc-level toc-level-3">
<li class="toc-item toc-item-h3">
<a class="toc-link toc-link-h3" href="#preparing-the-apples">
Preparing the apples
</a>
</li>
<li class="toc-item toc-item-h3">
<a class="toc-link toc-link-h3" href="#preparing-the-spice-mix">
Preparing the spice mix
</a>
</li>
</ol>
</li>
<li class="toc-item toc-item-h2">
<a class="toc-link toc-link-h2" href="#crust">
Crust
</a>
<ol class="toc-level toc-level-3">
<li class="toc-item toc-item-h3">
<a class="toc-link toc-link-h3" href="#preparing-the-dough">
Preparing the dough
</a>
</li>
<li class="toc-item toc-item-h3">
<a class="toc-link toc-link-h3" href="#the-criss-cross-top">
The criss-cross top
</a>
</li>
</ol>
</li>
</ol>
</li>
</ol>
</nav>
<h1 id="apple-pie-recipe">Apple Pie Recipe</h1>
<p>This is the world's best apple pie recipe...</p>
<div>
<h2 id="filling">Filling</h2>
<p>The filling is the best part...</p>
<h3 id="preparing-the-apples">Preparing the apples</h3>
<p>Cut the apples into 1/4 inch slices...</p>
<h3 id="preparing-the-spice-mix">Preparing the spice mix</h3>
<p>In a mixing bowl, combine sugar, cinnamon...</p>
</div>
<div>
<h2 id="crust">Crust</h2>
<p>How to make the perfect flaky crust...</p>
<h3 id="preparing-the-dough">Preparing the dough</h3>
<p>Combine flour, sugar, salt...</p>
<h3 id="the-criss-cross-top">The criss-cross top</h3>
<p>Cut the top crust into 1/2 inch strips...</p>
</div>
</body>
</html>
You can install rehype-toc via npm.
npm install rehype-toc
You'll probably want to install unified, rehype-parse, rehype-stringify, and rehype-slug as well.
npm install unified rehype-parse rehype-stringify rehype-slug
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 .use() method, optionally with an options object.
const unified = require("unified");
const toc = require("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 <h1> and <h2> 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
}
});
Rehype Rehype TOC supports the following options:
| Option | Type | Default | Description |
|---|---|---|---|
nav | boolean | true | Determines whether the table of contents is wrapped in a <nav> element. |
position | string | "afterbegin" | The position at which the table of contents should be inserted, relative to the <main> or <body> element. Can be "beforebegin", "afterbegin", "beforeend", or "afterend". See the insertAdjacentElement() docs 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 <nav> or <ol> element that contains the whole table of contents. |
cssClasses.list | string | toc-level | The CSS class name for all <ol> elements in the table of contents, including the top-level one. |
cssClasses.listItem | string | toc-item | The CSS class name for all <li> elements in the table of contents. |
cssClasses.link | string | toc-link | The CSS class name for all <a> elements in the table of contents. |
customizeTOC | function | no-op | 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. |
Contributions, enhancements, and bug-fixes are welcome! File an issue on GitHub and submit a pull request.
To build the project locally on your computer:
Clone this repo
git clone https://github.com/JS-DevTools/rehype-toc.git
Install dependencies
npm install
Build the code
npm run build
Run the tests
npm test
rehype-toc is 100% free and open-source, under the MIT license. Use it however you want.
Thanks to these awesome companies for their support of Open Source developers ❤
FAQs
A rehype plugin that adds a table of contents (TOC) to the page
The npm package rehype-toc receives a total of 5,161 weekly downloads. As such, rehype-toc popularity was classified as popular.
We found that rehype-toc demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
TypeScript is porting its compiler to Go, delivering 10x faster builds, lower memory usage, and improved editor performance for a smoother developer experience.
Research
Security News
The Socket Research Team has discovered six new malicious npm packages linked to North Korea’s Lazarus Group, designed to steal credentials and deploy backdoors.
Security News
Socket CEO Feross Aboukhadijeh discusses the open web, open source security, and how Socket tackles software supply chain attacks on The Pair Program podcast.