Skip to content

Linkify HTML headers and generate a TOC

License

Notifications You must be signed in to change notification settings

shelfio/table-of-contents

This branch is up to date with master.

Folders and files

NameName
Last commit message
Last commit date
Oct 16, 2024
Nov 5, 2021
Aug 15, 2023
Dec 3, 2024
Nov 5, 2021
Nov 5, 2021
Nov 5, 2021
Nov 5, 2021
Nov 5, 2021
Nov 5, 2021
Oct 30, 2023
Jul 13, 2022
Nov 5, 2021
Dec 3, 2024
Nov 5, 2021
Jan 28, 2025
Jan 30, 2023
Oct 30, 2023
Nov 5, 2021

Repository files navigation

table-of-contents CircleCI

Linkify HTML headers and generate a TOC.

Forked from node-toc

Rewritten in TypeScript & refactored to reduce bundle size (by not using entire lodash library)

Install

$ yarn add @shelf/table-of-contents

Usage

const toc = require('@shelf/table-of-contents');

toc.untag

Strip HTML tags from a string.

const stripped = toc.untag(html);

toc.anchor

Convert a string of text into something URL-friendly and not too ugly.

const anchor = toc.anchor(arbitraryText);

toc.unique

Get a unique name and store the returned name in names for future unique-name-gettingness.

const names = {};
const guaranteedUniqueAnchor1 = toc.unique(names, toc.anchor(arbitraryText));
const guaranteedUniqueAnchor2 = toc.unique(names, toc.anchor(arbitraryText));

toc.process

Anchorize all headers and inline a generated TOC, returning processed HTML.

const htmlWithAnchorsAndTOC = toc.process(html [, options]);

options

  • placeholder - RegExp - Used to match TOC placeholder. Defaults to /<!--\s*toc\s*-->/gi.
  • Because this method calls the toc.anchorize and toc.toc methods internally, their options may be specified as well.

toc.anchorize

Parse HTML, returning an array of header objects and anchorized HTML.

const obj = toc.anchorize(html [, options]);

options

  • headers - RegExp - Used to match HTML headers. Defaults to /<h(\d)(\s*[^>]*)>([\s\S]+?)<\/h\1>/gi.
  • tocMin - Number - Min header level to add to TOC. Defaults to 2.
  • tocMax - Number - Max header level to add to TOC. Defaults to 6.
  • anchorMin - Number - Min header level to anchorize. Defaults to 2.
  • anchorMax - Number - Max header level to anchorize. Defaults to 6.
  • header - String | Function - Lodash template string or function used to anchorize a header.

toc.toc

Generate TOC HTML from an array of header objects.

const obj = toc.toc(headers [, options]);

options

  • openUL - String | Function - Lodash template string or function used to generate the TOC.
  • closeUL - String | Function - Lodash template string or function used to generate the TOC.
  • openLI - String | Function - Lodash template string or function used to generate the TOC.
  • closeLI - String | Function - Lodash template string or function used to generate the TOC.
  • TOC - String | Function - Lodash template string or function used to wrap the generated TOC.

Examples

The default HTML is pretty awesome, but you can customize the hell out of the generated HTML, eg.

const processedHTML = toc.process(unprocessedHTML, {
  header: '<h<%= level %><%= attrs %> id="<%= anchor %>"><%= header %></h<%= level %>>',
  TOC: '<div class="toc"><%= toc %></div>',
  openUL: '<ul data-depth="<%= depth %>">',
  closeUL: '</ul>',
  openLI: '<li data-level="H<%= level %>"><a href="#<%= anchor %>"><%= text %></a>',
  closeLI: '</li>',
});

Publish

$ git checkout master
$ yarn version
$ yarn publish
$ git push origin master --tags

License

MIT © Shelf