Coder Social home page Coder Social logo

table-of-contents's Introduction

Growella Table of Contents

Build Status Code Climate

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' );

table-of-contents's People

Contributors

stevegrunwell avatar leepeterson avatar

Watchers

James Cloos avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.