Growella Table of Contents
This WordPress plugin automatically generates a Table of Contents for the current post., (*1)
Heads up! This plugin is being developed in the open, with the eventual goal of both powering dynamic tables of contents on Growella as well as being released on WordPress.org. That being said, the plugin is still very much under active development and may not be stable enough for production use!, (*2)
Usage
Insert a [toc] shortcode into your post content wherever you'd like the table of contents to appear. The plugin will automatically generate IDs for every heading in the post content, then build a list wherever you placed the shortcode., (*3)
For example, let's imagine you want to embed the table of contents after an introductory paragraph. You have absolute control over the placement by moving the shortcode:, (*4)
Introduction
...
[toc]
First topic
...
Second topic
...
For that example, the generated table of contents would look something like:, (*5)
- Introduction
- First topic
- Second topic
Shortcode options
The [toc] shortcode has a number of available arguments, which can be used to control the generated table of contents on a per-post basis. If you would prefer to change the defaults on a global level, please see the growella_table_of_contents_shortcode_defaults filter., (*6)
class
Extra HTML class names (space-separated) to apply to the table of contents. Default is an empty string., (*7)
For ease of styling, the rendered table of contents will always have .growella-table-of-contents., (*8)
Example
Add classes "sticky" and "special-nav" to the rendered table of contents., (*9)
[toc class="sticky special-nav"]
depth
Note: This argument has not yet been implemented., (*10)
Control how deeply the generated table of contents is nested:, (*11)
- -1
- Show all found headings (based on the
$tags argument) in a flat list. This is the default behavior.
- 0
- Show only the top-level headings. For example, if a H2-level heading has an H3-level (or higher) heading below it, only the link for the H2 would be displayed in the table of contents.
$n- Nest sub-headings in the table of contents until the list gets
$n levels deep.
A comma-separated list of tags that should be considered to be headings. Default is "h1,h2,h3"., (*12)
Example
To restrict the table of contents to only <h2> tags in your content, you can use the following shortcode:, (*13)
[toc tags="h2"]
title
A title to appear at the top of the table of contents. By default, this value is "Table of Contents". Passing an empty string (or any other "false-y" value) will prevent this heading from being created., (*14)
Example
Change the heading to "In this article:":, (*15)
[toc title="In this article:"]
Alternatively, if you'd prefer to not show a heading, pass an empty string:, (*16)
[toc title=""]
Available filters
Growella Table of Contents exposes several filters for use with the WordPress plugin API., (*17)
growella_table_of_contents_shortcode_defaults
Modify default settings for the Growella Table of Contents [toc] shortcode., (*18)
- array $defaults
- Default shortcode attributes.
This filter is ideal if you'd like to override the global defaults to better suit your theme, letting editors still override the new defaults on a per-post basis when needed., (*19)
Example
Change the default title to "In this article":, (*20)
/**
* Override default settings for Growella Table of Contents' [toc] shortcode.
*
* @param array $defaults Default shortcode attributes.
* @return array The modified $defaults.
*/
function mytheme_override_toc_defaults( $defaults ) {
$defaults['title'] = 'In this article';
return $defaults;
}
add_filter( 'growella_table_of_contents_shortcode_defaults', 'mytheme_override_toc_defaults' );
growella_table_of_contents_render_shortcode
Filter the Growella Table of Contents just before returning the rendered shortcode output., (*21)
<, (*22)
dl>
, (*23)
string $output
The rendered table of contents.
array $atts
The shortcode attributes used to build the table of contents.
array $links
The links used to build the table of contents.
Wallogit.com
