growella/table-of-contents

Automatically generate and render a Table of Contents for a post.

dev-develop 2017-02-20 15:32 UTC

Requires (Dev)

• php: ^5.5 || ^7.0
• ext-xml: *
• 10up/wp_mock: ^0.1.1
• codeclimate/php-test-reporter: ^0.3.2
• phpunit/phpunit: ^5.7
• stevegrunwell/wp-enforcer: ^0.4.1

MIT

• Growella
• Steve Grunwell

README

This WordPress plugin automatically generates a Table of Contents for the current post.

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!

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.

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:

<h2>Introduction</h2>
...

[toc]

<h2>First topic</h2>
...

<h2>Second topic</h2>
...

For that example, the generated table of contents would look something like:

• 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.

class

Extra HTML class names (space-separated) to apply to the table of contents. Default is an empty string.

For ease of styling, the rendered table of contents will always have .growella-table-of-contents.

Example

Add classes "sticky" and "special-nav" to the rendered table of contents.

[toc class="sticky special-nav"]

depth

Note: This argument has not yet been implemented.

Control how deeply the generated table of contents is nested:

-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.

tags

A comma-separated list of tags that should be considered to be headings. Default is "h1,h2,h3".

Example

To restrict the table of contents to only <h2> tags in your content, you can use the following shortcode:

[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.

Example

Change the heading to "In this article:":

[toc title="In this article:"]

Alternatively, if you'd prefer to not show a heading, pass an empty string:

[toc title=""]

Available filters

Growella Table of Contents exposes several filters for use with the WordPress plugin API.

growella_table_of_contents_shortcode_defaults

Modify default settings for the Growella Table of Contents [toc] shortcode.

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.

Example

Change the default title to "In this article":

/**
 * 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.

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.

growella_table_of_contents_link_anchor_text

Filter the anchor text for a table of contents link before it's put into a link.

string $anchor

The anchor text to be used when building the link.

DOMElement $element

A DOMElement object representing the DOM node.

Example

If headings are longer than 80 characters, truncate the link and append an ellipsis:

/**
 * Truncate anchor text in the table of contents to 80 characters.
 *
 * @param string $anchor  The anchor text to be used when building the link.
 * @return string The filtered $anchor text.
 */
function mytheme_truncate_toc_links( $anchor ) {
	if ( 80 < strlen( $anchor ) ) {
		$anchor = substr( $anchor, 0, 80 ) . '&hellip;';
	}

	return $anchor;
}
add_filter( 'growella_table_of_contents_link_anchor_text', 'mytheme_truncate_toc_links' );