toc-extract v1.1.0

toc-extract

Extracts a Table of Contents from HTML

Summary

toc-extract is a package for Node.js that can be used to extract a Table of Contents from HTML, using JSDOM.

Additionally, toc-extract defines a filter for the static site generator Eleventy.

Usage

Installation

To install toc-extract, run

npm install --save toc-extract

or

npm install --save-dev toc-extract

if you don't need toc-extract during your work's runtime (e.g. when only using toc-extract as a plugin for a static site generator).

From Node

The easiest way to use toc-extract from JavaScript is by using the function extractTOC, like so:

const html = '<h1 id="my-document">My Document</h1>...'
const toc = extractTOC(html) // '<ul><li><a href="#my-document">My Document</a></li>...</ul>'

The generated table of contents will contain links to all headings that have their id attribute set.

If you want more control about the generated table of contents, pass in an options object as the second parameter to extractTOC, like so:

const html = '<h1 id="my-document">My Document</h1><h2 id="section-1">Section One</h2>Lorem Ipsum...'
const toc = extractTOC(html, {minLevel: 2, listElement: "ol"}) // '<ol><li><a href="#section-1">Section One</a></li>...</ol>'

Options that are not set will be set to their default values, as indicated in the table below.

The following options are available:

If you want more control, consider using the functions extractHeadingStructure and buildTOCFromHeadingStructure, for which extractTOC is actually just a thin convenience layer.

As a Plugin for Eleventy

Basic usage

To use toc-extract within Eleventy, add it to your .eleventy.js like so:

const tocExtract = require("toc-extract/plugins/eleventy.js")

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(tocExtract)
}

A complete example project is available in the examples/eleventy directory.

If you want to create a table of contents for Markdown, it is recommended to additionally install markdown-it-anchor, as demonstrated in the example project, since by default, the Markdown renderer in Eleventy doesn't auto-generate heading IDs.

Site-wide Configuration

toc-extract can be configured site-wide by passing in an options object in your .eleventy.js like so:

const tocExtract = require("toc-extract/plugins/eleventy.js")

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(tocExtract, {listElement: "ol", minLevel: 2})
}

You can also customize the name of the filter, and even add multiple instances of the toc-extract filter, with different profiles:

const tocExtract = require("toc-extract/plugins/eleventy.js")

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(tocExtract, {filterName: "tocfoo", listElement: "ol"})
  eleventyConfig.addPlugin(tocExtract, {filterName: "tocbar", listElement: "ul", minLevel: 3})
}

Configuration Override

If you need to tweak the configuration of your table of contents, but don't want to change your site-wide configuration, you can also override the config right in your template, like so:

<nav>
    {{ content | toc: '{"minLevel": 1, "listElement": "ul"}' }}
</nav>

For template engines that support object literals, you can directly pass an options object in. Alternatively, you can pass in a JSON string, as demonstrated above.

Contributing

Feel free to contribute by posting issues on this repository's Issue Tracker.

Please note that pull requests are only accepted if they are in line with the licensing of the rest of the project (see below).

Copyright and Licensing

toc-extract is (C) 2022 Lucas Hinderberger

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

For details, please refer to the LICENCE file.

Maintainer and Contact

toc-extract is maintained by Lucas Hinderberger.

You can contact the maintainer via email at mail@lucas-hinderberger.de

The repository of toc-extract can be found at https://codeberg.org/lhinderberger/toc-extract

You're welcome to file issues and pull requests there.