Loading...

Blog

New plugin: bs TOC

bs TOC

bs TOC is a lightweight alternative to traditional WordPress Table of Contents plugins, offering custom settings, minimal code, and seamless Bootstrap integration.

Motivation and context

Previously, Bootscore’s documentation used the LuckyWP Table of Contents plugin to set anchor links for each section. The plugin offers extensive backend options, allowing users to configure global settings such as selecting themes, choosing colors, changing font sizes, controlling depth, excluding unwanted headings, and much more. However, it was difficult to control this plugin through code, and simple CSS overrides often required !important to work. Consequently, embedding the plugin seamlessly into the theme’s Bootstrap style was challenging.

Although LuckyWP Table of Contents was an overloaded yet still effective plugin, it reached its end of life in May, was no longer updated, and was removed from the WP plugin repository (edit: it’s back again) due to vulnerabilities reported by Solid Security.

At this point, we had to manually replace all 30 TOCs in the documentation, and even worse, on some client sites as well, including one with more than 400 pages where this plugin was active – Ouch! After testing several other TOC plugins like Easy Table of Contents, we encountered the same overloaded backend settings and decided to code our own TOC to avoid being dependent on plugin developers who might stop supporting them.

bs TOC

The new bs TOC plugin is built with a single PHP file containing just 200 lines of code, and it can do everything other TOC plugins do, just better. The TOC comes with list-unstyled nested ul elements, wrapped in a Bootstrap card with a title. It’s that simple.

Individual settings

Individual settings for each page where the TOC is active can be controlled by the shortcode or by adding classes:

  • The basic [bs-toc] shortcode fetches all h2 to h6 headings.
  • The h1 is excluded because this is the page title.
  • Headings from external content are excluded because they are not part of the page content.
  • Control the individual depth of headings in the shortcode. For example, [bs-toc depth="1"] fetches only h2 headings, while [bs-toc depth="2"] fetches all h2 and h3 headings, and so on.
  • Exclude individual unwanted headings by adding the bs-toc-hide class to a heading, or group multiple unwanted headings inside a div with the bs-toc-hide class.

Global settings

Global settings change the entire appearance and behavior on all TOC’s through filters:

Here are some quick examples of how the TOC can look like if some utility classes have been changed.

Shrink browser window to <lg size to view responsive TOC.

Get it

Have a great day!

To top