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.
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
});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 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.
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.
Tocbot builds a table of contents (TOC) from headings in an HTML document. This is useful for documentation websites or long markdown pages because it makes them easier to navigate. This library was inspired by Tocify, the main difference is that Tocbot uses native DOM methods and avoids the jQuery & jQuery UI dependencies.
You can use npm to install it or include the script on the page with HTML.
Install it with npm.
npm install --save tocbot
OR
Include the script at the bottom of the page before the closing body tag.
<script src="/assets/js/tocbot.js"></script>
CSS is used for expanding & collapsing groupings and some basic styling.
<link rel="stylesheet" href="/assets/css/tocbot.css">
OR
If you installed it with npm and use sass / postcss you might try importing the styles from 'node_modules', see the includePath option documentation for more info
@import 'tocbot/src/scss/tocbot-core';
@import 'tocbot/src/scss/tocbot-default-theme';
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-toc-content',
// Which headings to grab inside of the contentSelector element.
headingSelector: 'h1, h2, h3',
});
If content in the div has changed then trigger a refresh (optionally with new options).
tocbot.refresh();
If you'd like to add your page to this list open a pull request.
This library uses vanilla JavaScript. It is less than 350 bytes of CSS and about 3.6Kb of JavaScript (minified and gzipped). The only dependency this script has is zenscroll (which is small and has no dependencies).
This script works in all modern browsers and IE 9+.
Make sure rendered headings have id attributes, some markdown libraries (like marked) already do this.
// Where to render the table of contents.
tocSelector: '.js-toc',
// Where to grab the headings to build the table of contents.
contentSelector: '.js-toc-content',
// Which headings to grab inside of the contentSelector element.
headingSelector: 'h1, h2, h3',
// Headings that match the ignoreSelector will be skipped.
ignoreSelector: '.js-toc-ignore',
// Main class to add to links.
linkClass: 'toc-link',
// Extra classes to add to links.
extraLinkClasses: '',
// Class to add to active links,
// the link corresponding to the top most heading on the page.
activeLinkClass: 'is-active-link',
// Main class to add to lists.
listClass: 'toc-list',
// Extra classes to add to lists.
extraListClasses: '',
// 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: 'is-collapsible',
// Class to add to list items.
listItemClass: 'toc-list-item',
// 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.
// The sections that are hidden will open
// and close as you scroll to headings within them.
collapseDepth: 0,
// Smooth scrolling enabled.
smoothScroll: true,
// Smooth scroll duration.
smoothScrollDuration: 420,
// Callback for scroll end (requires: smoothScroll).
scrollEndCallback: function (e) {},
// Headings offset between the headings and the top of the document.
headingsOffset: 0,
// Timeout between events firing to make sure it's
// not too rapid (for performance reasons).
throttleTimeout: 50,
// Element to add the positionFixedClass to.
positionFixedSelector: null,
// 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',
// includeHtml can be set to true to include the HTML markup from the
// heading node instead of just including the textContent.
includeHtml: false
Initialize tocbot with an options object.
tocbot.init(options)
Destroy tocbot and remove event listeners.
tocbot.destroy()
Refresh tocbot if the document changes and it needs to be rebuilt.
tocbot.refresh()
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.
If you want to open a pull request just fork the repo but please make sure all tests and lint pass.
npm run test
You can run tests through node-inspector.
For now, you may need to use node v6 or lower...
nvm use 6
Once you're on node v6 or lower:
npm install node-inspector
Now that node-inspector is installed, you can run the tests!
npm run test:debug
npm version <patch|minor|major>npm publishFAQs
Generate a table of contents based on the heading structure of a html document.
The npm package tocbot receives a total of 1,226,235 weekly downloads. As such, tocbot popularity was classified as popular.
We found that tocbot demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers 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
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.