NanoTOC

Documentation WordPress Plugin Created by Saqib Hanif

Overview

NanoTOC is a fast, lightweight Table of Contents plugin for WordPress. It generates a TOC from your headings and supports nested (hierarchical) or flat lists, plus smooth scrolling with an optional offset for sticky headers.

Quick start

Install

wp-content/plugins/nanotoc/
				  light-toc.php
				  assets/light-toc.js

Activate the plugin in WP Admin → Plugins, then configure it under Settings → NanoTOC.

Usage

Automatic insert

Enable Auto insert. The TOC will be placed at the top of the content when headings are present.

Manual insert (shortcode)

Place the shortcode where you want the TOC to appear:

[nanotoc]
[light_toc]

Settings reference

Enable Turn the plugin on/off globally.
Post types Choose where TOC can be generated (posts, pages, or custom post types).
Headings to include Select H1–H6 (example: only H2 + H3).
List style Nested (hierarchical) or Flat (linear).
Auto insert Insert at the top when shortcode is not used.
Label Title displayed above the TOC (default: “Table of Contents”).
Smooth scroll Smoothly scroll to headings when clicking TOC links.
Scroll offset (px) Extra offset for sticky headers. The WP admin bar height is automatically added when present.

Styling

NanoTOC ships without heavy styling so it inherits your theme typography by default. To customize, target these classes:

.nanotoc
.nanotoc__title
.nanotoc__list
.nanotoc__item
.nanotoc__link

.light-toc
.light-toc__title
.light-toc__list
.light-toc__item
.light-toc__link

Excluding headings

To exclude a specific heading from the TOC, add data-toc="false" to the heading.

<h2 data-toc="false">Hidden from TOC</h2>

Smooth scroll & offset

If your headings are hidden behind a sticky header after clicking a TOC link, increase Scroll offset (px) until the heading is fully visible.

NanoTOC also accounts for the WordPress admin bar automatically (when it exists).

Troubleshooting

  • If TOC does not appear, confirm your content contains real headings like <h2>/<h3>.
  • If a theme/builder renders headings in non-standard markup, TOC generation may not detect them.
  • If another script overrides smooth scrolling, disable that script or keep NanoTOC smooth scroll enabled (it runs early in the click phase).
  • If you find an issue or want to request a feature, please contact the author.

Licensing

NanoTOC is licensed under GPL v2.0 or later.

See LICENSE.txt or https://www.gnu.org/licenses/gpl-2.0.html.