tocbot

What is tocbot?

The tocbot npm package is designed to generate a table of contents (TOC) based on the headings in a given HTML document. It automatically creates a TOC that can be styled and configured to enhance navigation within long documents, making it easier for users to jump to different sections.

What are tocbot's main functionalities?

Generate TOC

This feature allows you to generate a table of contents by specifying the selectors for the TOC container, the content where the headings are located, and the headings to be included in the TOC.

tocbot.init({
  tocSelector: '.js-toc',
  contentSelector: '.js-toc-content',
  headingSelector: 'h1, h2, h3'
});

Customize TOC Styling

This feature allows you to customize the classes applied to the TOC links, active links, list, and list items, enabling you to style the TOC to match your site's design.

tocbot.init({
  tocSelector: '.js-toc',
  contentSelector: '.js-toc-content',
  headingSelector: 'h1, h2, h3',
  linkClass: 'toc-link',
  activeLinkClass: 'is-active-link',
  listClass: 'toc-list',
  listItemClass: 'toc-list-item'
});

Smooth Scrolling

This feature enables smooth scrolling when a user clicks on a TOC link, providing a better user experience.

tocbot.init({
  tocSelector: '.js-toc',
  contentSelector: '.js-toc-content',
  headingSelector: 'h1, h2, h3',
  scrollSmooth: true
});

Collapse Sub-Headings

This feature allows you to specify the depth of headings that should be collapsible, helping to keep the TOC concise and focused on higher-level headings.

tocbot.init({
  tocSelector: '.js-toc',
  contentSelector: '.js-toc-content',
  headingSelector: 'h1, h2, h3',
  collapseDepth: 3
});

Other packages similar to tocbot

markdown-toc

The markdown-toc package generates a TOC for markdown files. Unlike tocbot, which operates on HTML content in the browser, markdown-toc is used primarily in Node.js environments or as part of a build process for markdown files.

doctoc

Doctoc is another tool for generating a TOC for markdown files, which can be used in a command-line environment. It is similar to markdown-toc but also supports updating existing TOCs within a document.

toc

The toc package is a Node.js module that generates a JSON representation of a TOC for HTML content. It differs from tocbot in that it does not provide the functionality to automatically insert the TOC into a webpage.

README

---

template: default title: Tocbot

Introduction

tocbot is a small script to build a table of contents (TOC) from headings in an HTML document. tocbot works well with Smooth Scroll and together they provide an experience very similar to Tocify.

This script is particularly useful for documentation websites or long markdown pages.

Checkout the Demo

Get Started

You can include the script on the page with HTML or use npm to install it.

Include JS

Include the script at the bottom of the page before the closing body tag

<script src="http://optimizely.github.io/tocbot/js/tocbot.js"></script>

OR

Install it with npm

npm install --save tocbot

And require it

var tocbot = require('tocbot');

Include CSS

CSS is used for expanding & collapsing groupings and some basic styling. The core of what's required is only 24 lines unminified.

<link rel="stylesheet" href="http://optimizely.github.io/tocbot/css/style.css">

OR

If you installed it with npm and use sass / postcss you might try importing the styles from the folder in 'node_modules', see the includePath docs for more info

@import 'tocbot/src/scss/style';

Usage

Initialize the script

tocbot.init({
  // Where to render the table of contents.
  tocSelector: '.js-toc',
  // Where to grab the headings to build the table of contents.
  contentSelector: '.js-content',
  // Optionally include reference to smoothScroll.
  smoothScroll: smoothScroll || window.smoothScroll
});

If content in the div has changed then trigger a refresh (optionally with new options).

tocbot.refresh();

Requirements

There is no need for jQuery as this library uses vanilla javascript.

There are no external dependencies for this script, besides Smooth Scroll (which also has no dependencies) should you choose to include it.

This script works in all modern browsers and IE > 9. To get support for older versions of IE please use polyfills.

Make sure rendered headings have id attributes, github pages and many markdown renderers (like marked) already do this.

API

Options

var defaultOptions = {
  // Where to render the table of contents.
  tocSelector: '.js-toc',
  // Where to grab the headings to build the table of contents.
  contentSelector: '.js-content',


  // Reference to smoothScroll
  smoothScroll: undefined,
  // smoothScroll Options
  smoothScrollOptions: {
    easing: 'easeInOutCubic',
    offset: 0,
    speed: 300, // animation duration.
    updateURL: true,
  },


  // Which headings to grab inside of the contentSelector element.
  headingsToSelect: [
    'h1',
    'h2',
    'h3',
    'h4',
    'h5',
  ],
  // Class to add to active links (the link corresponding to the top most heading on the page).
  activeLinkClass: 'is-active-link',
  // Headings that match the excludeSelector will be skipped.
  excludeSelector: '.skip-toc',
  // Fixed position class to add to make sidebar fixed after scrolling down past the fixedSidebarOffset.
  positionFixedClass: 'is-position-fixed',
  // fixedSidebarOffset can be any number but by default is set to auto which sets the fixedSidebarOffset to the sidebar element's offsetTop from the top of the document on init.
  fixedSidebarOffset: 'auto',


  // Main class to add to links.
  linkClass: 'toc-link',
  // Extra classes to add to links.
  extraLinkClasses: 'color--base',
  // Main class to add to lists.
  listClass: 'toc-list',
  // Extra classes to add to lists.
  extraListClasses: 'soft--left',
  // Headings offset between the headings and the top of the document (helps with weird rounding bugs that pop up).
  headingsOffset: 2,


  // Class that gets added when a list should be collapsed.
  isCollapsedClass: 'is-collapsed',
  // Class that gets added when a list should be able to be collapsed but isn't necessarily collpased.
  collapsibleClass: 'collapsible',
  // How many heading levels should not be collpased. For example, number 6 will show everything since there are only 6 heading levels and number 0 will collpase them all.
  collapseDepth: 0,
};

Methods

.init

Initialize tocbot with an options object.

tocbot.init(options)

.destroy

Destroy tocbot.

tocbot.destroy()

.refresh

Refresh tocbot.

tocbot.refresh()

Running Tests

gulp test

Roadmap

• Tests
• List size of js and css
• Split into smaller files (core, util/data, util/dom)
• Blog post to announce it!!!
• Eventually, a place to drop in markdown to preview it.
• React.js support.
• Debounce option.

Changelog

v1.0

• Publicly launched

Contributing

Contributions and suggestions are welcome. Please feel free to open an issue if you run into a problem or have a feature request. I'll do my best to respond in a timely fashion.

License

MIT

Changelog

1.0.0

• First published source code.