JSPM – tocbot@1.0.0

Package Exports

tocbot

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (tocbot) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

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>

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">

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