@smals-webagency/toc
v3.0.0
Published
Automatic generation of a table of contents.
Downloads
3
Keywords
Readme
TOC
smalsToc is a script that generates a Table of Contents (TOC) based on the headings within a specified content element. It provides a simple way to create a navigation structure for your content.
Getting started
Install with npm: npm install @smals-webagency/toc
Include
1. smalsToc with jQuery
Include jQuery: ensure that jQuery is included in your project.
<script src="path/to/jquery.min.js"></script> <script src="path/to/smals-toc-jquery.js"></script>Call
smalsTocon an element: call thesmalsTocmethod on an HTML element to generate the TOC.$('#toc').smalsToc({ // Options go here });
2. smalsToc without jQuery
Include
smalsTocscript: include thesmalsTocscript in your project.<script src="path/to/smals-toc.js"></script>Call
smalsTocon an element: call thesmalsTocmethod on an HTML element to generate the TOC.document.getElementById('toc').smalsToc({ // Options go here });
3. smalsToc bundle for webpack
With jQuery:
// app.js
import smalsToc from './smals-toc-jquery-bundle';
$('#toc').smalsToc({
// Options go here
});Without jQuery:
// app.js
import smalsToc from './smals-toc-bundle';
document.getElementById('toc').smalsToc({
// Options go here
});Options
The smalsToc script supports the following options:
| Name | Default value | Description |
|:-------------------|:----------------|:---------------------------------------------------------------------------------------------------------------------------------|
| contentElementId | 'toc-content' | Specifies the ID of the content element containing the headings. | |
| listTag | 'ul' | Specifies the HTML tag to be used for the list (e.g., 'ul' or 'ol'). |
| listClass | '' | Specifies the CSS class to be applied to the list. |
| listItemClass | '' | Specifies the CSS class to be applied to each list item. |
| linkClass | '' | Specifies the CSS class to be applied to each anchor link. |
| headings | 'h2, h3, h4' | Specifies the headings to be included in the Table of Contents. It should be a comma-separated string of HTML heading tags. |
| ignoreClass | 'toc-ignore' | Specifies the CSS class that, when applied to a heading or its ancestors, excludes the heading from the Table of Contents. |
| scrollSpy | true | Enable or disable the scrollSpy functionality. When set to true, the TOC will automatically highlight the active section based on the user's scrolling. |
Functionality
- The script creates a Table of Contents based on the headings within the specified content element.
- Each heading is transformed into an anchor link within the TOC.
- The script normalizes heading text to create unique anchor names.
- The TOC structure mirrors the heading structure, maintaining hierarchy.
- Optionally, the script supports custom CSS classes for styling.
Example
<body>
<div id="toc-content">
<h2>Section 1</h2>
<h3>Subsection 1.1</h3>
<h3 class="toc-ignore">Subsection 1.2 (Ignored)</h3>
<h2>Section 2</h2>
</div>
<div id="toc"></div>
<!-- Include jQuery -->
<script src="path/to/jquery.min.js"></script>
<!-- Include smalsToc script -->
<script src="path/to/smalsToc-jquery.js"></script>
<script>
$('#toc').smalsToc({
contentElementId: 'toc-content',
listTag: 'ul',
listClass: 'custom-list',
listItemClass: 'custom-list-item',
linkClass: 'custom-link',
headings: 'h2, h3',
ignoreClass: 'toc-ignore'
});
</script>
</body>