PloverToc

About

PloverToc is a simple and efficient WordPress plugin that automatically generates a table of contents (TOC) for your posts, pages and custom post types. By using a shortcode, you can easily insert a TOC that helps your readers navigate through your content by providing direct links to different sections. You can also customize the heading levels included in the TOC.

It’s focused on providing a sound TOC interface with no “bells and whistles”. While it does come with some helpful features for customizing the included heading levels via shortcode attributes, the esthetic design and styling of the TOC is left to the user to implement using their own CSS.

Additionally, it does add SiteNavigationElement schema to enhance your site’s SEO.

Features

• Automatically generate a table of contents for your posts and pages.
• Customizable heading levels to include in the TOC (e.g., H1, H2, H3).
• Collapse TOC on page upload, without any JavaScript.
• This plugin is 100% javascript-free.
• Simple shortcode to insert the TOC anywhere in your content.
• Compatible with the latest version of WordPress with Gutenberg.
• Compatible with the Classic Editor as well.
• Users are responsible for styling the TOC using their own CSS.
• Custom post types are supported, as long as their content is output with the the_content() template tag.
• Will generate SiteNavigationElement schema to enhance SEO, this can be turned off via shortcode attribute.

Requirements

• PHP >= 8.0
• WordPress >= 6.4.0

Contributing

The best way to contribute to the development of this plugin is by participating on the GitHub project:

https://github.com/PloverHub/plover-toc

There are many ways you can contribute:

• Raise an issue if you found one
• Create/send us a Pull Request with your bug fixes and/or new features
• Provide us with your feedback and/or suggestions for any improvement or enhancement
• Translation – this is an area we are yet to do

0.7.0 (Aug 11, 2024)

• Rebrand the plugin from “ClaraPress” to “PloverToc”:
  • The WordPress Plugin Review Team warned of infringement on the WordPress trademark by virtue of the portmanteau effect in which the “Press” part in “ClaraPress” was deemed as a composition of Clara and WordPress and hence a violation of the WordPress trademark policy.
  • This also meant I had to abandon my ClaraPress.com domain name and move to a new one, namely PloverHub.com

0.6.0 (Jun 30, 2024)

• Added customizable heading levels for TOC using top_level and depth shortcode attributes.
• Implemented a filter clarapress_toc_summary_text to allow overriding the summary text in the TOC.
• Added localization support for summary text using the __() function and text domain clarapress-toc.
• Ensured compatibility with PHP 8.0+ and WordPress 6.4+
• Added a section for styling guidelines and provided an HTML template for users to see CSS classes to target.
• Updated documentation to include usage examples and customization options.
• Added SiteNavigationElement schema to enhance SEO with an option to enable/disable it via shortcode attribute schema.

0.5.0 (Jun 27, 2024)

• Workout a Github Action to automate the release process whenever a new tag is pushed to the repository.

0.1.0 (Nov 4, 2023)

• Initial commit of working code for the benefit of everyone who needs this plugin

1) Through the WordPress plugins screen, Add New Plugin
– Alternatively, you can download the plugin from the WordPress Plugin Directory and upload it to your site.
2) Search for “plover toc”
3) Install and Activate
4) Use the shortcode [plovertoc] in your content
– simply add the shortcode [plovertoc] to your post or page where you want the table of contents to appear.
5) (Optional) Customize the top_level, depth, and schema attributes in the shortcode to specify which heading levels to include.
– You can customize the heading levels included in the TOC using the top_level and depth attributes in the shortcode. For example: [plovertoc top_level="2" depth="3"]
– You can also turn off the SiteNavigationElement schema using the schema attribute in the shortcode. For example: [plovertoc schema="false"]

Shortcode Attributes

[plovertoc top_level="2" depth="4"] would mean generating a TOC that includes only H2, H3, H4 and H5 headings.
[plovertoc top_level="1" depth="3"] would mean generating a TOC that includes only H1, H2, and H3 headings.
[plovertoc top_level="1" depth="2"] would mean generating a TOC that includes only H1, and H2 headings.

Styling

You can target the css class “plover-toc-wrapper” and “plover-toc-items”. See below the actual HTML structure to guide you.

`html

Open Table of contents

• {anchor_text}}
  • {anchor_text}}

`

Localization

PloverToc supports localization. To translate the plugin into your language, add the appropriate translation files in the languages directory. The text domain for this plugin is plover-toc.

You can also customize the summary text of the table of contents by using the plover_toc_summary_text filter as shown below. The default summary text is localizable.

Changing the header (summary) text of the TOC

To customize the summary text of the table of contents, use the plover_toc_summary_text filter.

Example to change summary text:
php
function custom_toc_summary_text(string $text)
{
return __('My Custom Table of Contents', 'plover-toc');
}
add_filter('plover_toc_summary_text', 'custom_toc_summary_text');