Below, you’ll find a detailed guide on how to add the Table of Contents Plus Shortcodes to your WordPress website, including their parameters, examples, and PHP function code. Additionally, we’ll assist you with common issues that might cause the Table of Contents Plus Plugin shortcodes not to show or not to work correctly.
Before starting, here is an overview of the Table of Contents Plus Plugin and the shortcodes it provides:
"Table of Contents Plus is a dynamic WordPress plugin that enhances your site's usability by generating a detailed table of contents. Perfect for long articles and content-heavy pages."
- [toc]
- [no_toc]
- [sitemap]
- [sitemap_pages]
- [sitemap_categories]
- [sitemap_posts]
Table of Contents Plus [toc] Shortcode
The ‘toc’ shortcode is used to generate a table of contents in a WordPress post. This shortcode pulls various attributes, such as ‘label’, ‘label_show’, ‘label_hide’, etc., from the options set in the table-of-contents-plus plugin. It allows customization of the table of contents per post, including the visibility, wrapping, heading levels, and more. It also re-enqueues scripts if certain conditions are met.
Shortcode: [toc]
Parameters
Here is a list of all possible toc shortcode parameters and attributes:
label– Specifies the heading text of the table of contents.label_show– Defines the text to display for showing the table of contents.label_hide– Specifies the text to display for hiding the table of contents.no_label– If set to true, the heading text will not be displayed.class– Adds a custom CSS class to the table of contents container.wrapping– Controls the alignment of the table of contents. It can be ‘left’ or ‘right’.heading_levels– Determines the heading levels to include in the table of contents.exclude– Allows specific headings to be excluded from the table of contents.collapse– If set to true, the table of contents will be hidden by default.no_numbers– If set to true, the table of contents will not display any numbering.start– Sets the starting number for the table of contents.
Examples and Usage
Basic example – The following shortcode will generate a Table of Contents with default settings.
[toc /]Advanced examples
Adding a custom label to the Table of Contents:
[toc label="My Custom TOC" /]Displaying the Table of Contents with a specific class:
[toc class="my-toc-class" /]Excluding specific headings from the Table of Contents:
[toc exclude="Heading 1, Heading 2" /]Forcing the Table of Contents to start collapsed:
[toc collapse=true /]Removing numbers from the Table of Contents:
[toc no_numbers=true /]Setting the start level of the Table of Contents:
[toc start=2 /]Setting specific heading levels to include in the Table of Contents:
[toc heading_levels="1,2,3" /]PHP Function Code
In case you have difficulties debugging what causing issues with [toc] shortcode, check below the related PHP functions code.
Shortcode line:
add_shortcode( 'toc', [ $this, 'shortcode_toc' ] );Shortcode PHP function:
function shortcode_toc( $attributes ) {
$atts = shortcode_atts(
[
'label' => $this->options['heading_text'],
'label_show' => $this->options['visibility_show'],
'label_hide' => $this->options['visibility_hide'],
'no_label' => false,
'class' => false,
'wrapping' => $this->options['wrapping'],
'heading_levels' => $this->options['heading_levels'],
'exclude' => $this->options['exclude'],
'collapse' => false,
'no_numbers' => false,
'start' => $this->options['start'],
],
$attributes
);
$re_enqueue_scripts = false;
if ( $atts['no_label'] ) {
$this->options['show_heading_text'] = false;
}
if ( $atts['label'] ) {
$this->options['heading_text'] = wp_kses_post( html_entity_decode( $atts['label'] ) );
}
if ( $atts['label_show'] ) {
$this->options['visibility_show'] = wp_kses_post( html_entity_decode( $atts['label_show'] ) );
$re_enqueue_scripts = true;
}
if ( $atts['label_hide'] ) {
$this->options['visibility_hide'] = wp_kses_post( html_entity_decode( $atts['label_hide'] ) );
$re_enqueue_scripts = true;
}
if ( $atts['class'] ) {
$this->options['css_container_class'] = wp_kses_post( html_entity_decode( $atts['class'] ) );
}
if ( $atts['wrapping'] ) {
switch ( strtolower( trim( $atts['wrapping'] ) ) ) {
case 'left':
$this->options['wrapping'] = TOC_WRAPPING_LEFT;
break;
case 'right':
$this->options['wrapping'] = TOC_WRAPPING_RIGHT;
break;
default:
// do nothing
}
}
if ( $atts['exclude'] ) {
$this->options['exclude'] = $atts['exclude'];
}
if ( $atts['collapse'] ) {
$this->options['visibility_hide_by_default'] = true;
$re_enqueue_scripts = true;
}
if ( $atts['no_numbers'] ) {
$this->options['ordered_list'] = false;
}
if ( is_numeric( $atts['start'] ) ) {
$this->options['start'] = $atts['start'];
}
if ( $re_enqueue_scripts ) {
do_action( 'wp_enqueue_scripts' );
}
// if $atts['heading_levels'] is an array, then it came from the global options
// and wasn't provided by per instance
if ( $atts['heading_levels'] && ! is_array( $atts['heading_levels'] ) ) {
// make sure they are numbers between 1 and 6 and put into
// the $clean_heading_levels array if not already
$clean_heading_levels = [];
foreach ( explode( ',', $atts['heading_levels'] ) as $heading_level ) {
if ( is_numeric( $heading_level ) ) {
$heading_level = (int) $heading_level;
if ( 1 <= $heading_level && $heading_level <= 6 ) {
if ( ! in_array( $heading_level, $clean_heading_levels, true ) ) {
$clean_heading_levels[] = (int) $heading_level;
}
}
}
}
if ( count( $clean_heading_levels ) > 0 ) {
$this->options['heading_levels'] = $clean_heading_levels;
}
}
if ( ! is_search() && ! is_archive() && ! is_feed() ) {
return '<!--TOC-->';
} else {
return '';
}
}
Code file location:
table-of-contents-plus/table-of-contents-plus/includes/class-toc-plus.phpTable of Contents Plus [no_toc] Shortcode
[no_toc] shortcode disables the table of contents on a specific page. When inserted, it instructs the ‘table-of-contents-plus’ plugin not to display the TOC.
Shortcode: [no_toc]
Examples and Usage
Basic example – A simple usage of the ‘no_toc’ shortcode to hide the table of contents on a specific page or post.
[no_toc]Advanced examples
Even though the ‘no_toc’ shortcode does not accept any parameters, you can combine it with other shortcodes for more advanced usage. Below are a few examples:
Combining the ‘no_toc’ shortcode with a ‘contact-form’ shortcode. This will display the contact form but hide the table of contents on the page.
[no_toc][contact-form id="1"]Using the ‘no_toc’ shortcode in conjunction with a ‘gallery’ shortcode. This will display the gallery without showing the table of contents on the page.
[no_toc]PHP Function Code
In case you have difficulties debugging what causing issues with [no_toc] shortcode, check below the related PHP functions code.
Shortcode line:
add_shortcode( 'no_toc', [ $this, 'shortcode_no_toc' ] );Shortcode PHP function:
function shortcode_no_toc( $atts ) {
$this->show_toc = false;
return '';
}
Code file location:
table-of-contents-plus/table-of-contents-plus/includes/class-toc-plus.phpTable of Contents Plus [sitemap] Shortcode
‘Sitemap’ shortcode is a tool that generates a sitemap on your WordPress site. It displays a list of pages and categories if enabled in the options. The function ‘shortcode_sitemap’ checks if page and category listing are enabled. If so, it creates an HTML string with a div class ‘toc_sitemap’. Inside, it lists pages and categories in unordered lists.
Shortcode: [sitemap]
Examples and Usage
Basic example – Display a sitemap using the shortcode. This will show a list of all pages and categories if it’s enabled in the plugin’s settings.
[sitemap /]PHP Function Code
In case you have difficulties debugging what causing issues with [sitemap] shortcode, check below the related PHP functions code.
Shortcode line:
add_shortcode( 'sitemap', [ $this, 'shortcode_sitemap' ] );Shortcode PHP function:
function shortcode_sitemap( $atts ) {
$html = '';
// only do the following if enabled
if ( $this->options['sitemap_show_page_listing'] || $this->options['sitemap_show_category_listing'] ) {
$html = '<div class="toc_sitemap">';
if ( $this->options['sitemap_show_page_listing'] ) {
$html .=
'<h' . $this->options['sitemap_heading_type'] . ' class="toc_sitemap_pages">' . htmlentities( $this->options['sitemap_pages'], ENT_COMPAT, 'UTF-8' ) . '</h' . $this->options['sitemap_heading_type'] . '>' .
'<ul class="toc_sitemap_pages_list">' .
wp_list_pages(
[
'title_li' => '',
'echo' => false,
]
) .
'</ul>';
}
if ( $this->options['sitemap_show_category_listing'] ) {
$html .=
'<h' . $this->options['sitemap_heading_type'] . ' class="toc_sitemap_categories">' . htmlentities( $this->options['sitemap_categories'], ENT_COMPAT, 'UTF-8' ) . '</h' . $this->options['sitemap_heading_type'] . '>' .
'<ul class="toc_sitemap_categories_list">' .
wp_list_categories(
[
'title_li' => '',
'echo' => false,
]
) .
'</ul>';
}
$html .= '</div>';
}
return $html;
}
Code file location:
table-of-contents-plus/table-of-contents-plus/includes/class-toc-plus.phpTable of Contents Plus [sitemap_pages] Shortcode
‘Sitemap_pages’ is a shortcode that generates a sitemap of all pages on your WordPress site. It allows customization of the heading type, label, and exclusion of specific pages. If ‘no_label’ is set to false, it displays a heading with the label. The ‘child_of’ attribute allows you to specify a parent page, displaying only its child pages. The generated sitemap is wrapped in a div with a class of ‘toc_sitemap’.
Shortcode: [sitemap_pages]
Parameters
Here is a list of all possible sitemap_pages shortcode parameters and attributes:
heading– Defines the size of the sitemap heading (values range from 1 to 6).label– The text that will be displayed as the sitemap’s title.no_label– If set to true, the sitemap title will be hidden.exclude– Pages to be excluded from the sitemap, specified by their IDs.exclude_tree– Excludes a page and all its child pages, specified by the parent page ID.child_of– Displays only the child pages of a specific page, specified by its ID.
Examples and Usage
Basic example – Display a sitemap of the pages on your website.
[sitemap_pages /]Advanced examples
Display a sitemap of the pages on your website with a specific heading type and label.
[sitemap_pages heading=3 label="Site Map" /]Display a sitemap of the pages on your website excluding certain pages. Here, the pages with IDs 2 and 5 will be excluded.
[sitemap_pages exclude="2,5" /]Display a sitemap of the pages on your website excluding a certain tree of pages. Here, the tree starting with the page with ID 3 will be excluded.
[sitemap_pages exclude_tree="3" /]Display a sitemap of the pages on your website showing only the children of a specific page. Here, only the children of the page with ID 4 will be displayed.
[sitemap_pages child_of="4" /]Display a sitemap of the pages on your website without a label.
[sitemap_pages no_label=true /]PHP Function Code
In case you have difficulties debugging what causing issues with [sitemap_pages] shortcode, check below the related PHP functions code.
Shortcode line:
add_shortcode( 'sitemap_pages', [ $this, 'shortcode_sitemap_pages' ] );Shortcode PHP function:
function shortcode_sitemap_pages( $attributes ) {
$atts = shortcode_atts(
[
'heading' => $this->options['sitemap_heading_type'],
'label' => $this->options['sitemap_pages'],
'no_label' => false,
'exclude' => '',
'exclude_tree' => '',
'child_of' => 0,
],
$attributes
);
$atts['heading'] = intval( $atts['heading'] ); // make sure it's an integer
if ( $atts['heading'] < 1 || $atts['heading'] > 6 ) { // h1 to h6 are valid
$atts['heading'] = $this->options['sitemap_heading_type'];
}
if ( 'current' === strtolower( $atts['child_of'] ) ) {
$atts['child_of'] = get_the_ID();
} elseif ( is_numeric( $atts['child_of'] ) ) {
$atts['child_of'] = intval( $atts['child_of'] );
} else {
$atts['child_of'] = 0;
}
$html = '<div class="toc_sitemap">';
if ( ! $atts['no_label'] ) {
$html .= '<h' . $atts['heading'] . ' class="toc_sitemap_pages">' . htmlentities( $atts['label'], ENT_COMPAT, 'UTF-8' ) . '</h' . $atts['heading'] . '>';
}
$html .=
'<ul class="toc_sitemap_pages_list">' .
wp_list_pages(
[
'title_li' => '',
'echo' => false,
'exclude' => $atts['exclude'],
'exclude_tree' => $atts['exclude_tree'],
'hierarchical' => true,
'child_of' => $atts['child_of'],
]
) .
'</ul>' .
'</div>';
return $html;
}
Code file location:
table-of-contents-plus/table-of-contents-plus/includes/class-toc-plus.phpTable of Contents Plus [sitemap_categories] Shortcode
‘Sitemap_categories’ shortcode is a tool that generates a sitemap of all categories. It allows customization of the heading type, label, and the option to exclude specific categories. The output is a well-formatted HTML structure. The shortcode ensures the heading is valid, between h1 and h6.
Shortcode: [sitemap_categories]
Parameters
Here is a list of all possible sitemap_categories shortcode parameters and attributes:
heading– defines the heading level for the categories list (from 1 to 6)label– sets the text for the heading of the categories listno_label– if set to true, no heading will be displayedexclude– IDs of categories to be excluded from the listexclude_tree– IDs of parent categories to exclude along with their child categories
Examples and Usage
Basic example – Show a sitemap of your categories without any exclusions or specific heading level.
[sitemap_categories]Advanced examples
Display a sitemap of your categories with a custom heading level. In this case, the heading level is set to 3.
[sitemap_categories heading=3]Display a sitemap of your categories with custom label. The label is set to “My Custom Categories”.
[sitemap_categories label="My Custom Categories"]Exclude certain categories from your sitemap. The categories with IDs 5 and 7 are excluded in this case.
[sitemap_categories exclude="5,7"]Exclude a category and all its child categories from your sitemap. The category with ID 5 and its child categories are excluded in this case.
[sitemap_categories exclude_tree="5"]Combine different parameters to customize the output of your sitemap. In this case, the heading level is set to 3, the label is set to “My Custom Categories”, and the categories with IDs 5 and 7 are excluded.
[sitemap_categories heading=3 label="My Custom Categories" exclude="5,7"]PHP Function Code
In case you have difficulties debugging what causing issues with [sitemap_categories] shortcode, check below the related PHP functions code.
Shortcode line:
add_shortcode( 'sitemap_categories', [ $this, 'shortcode_sitemap_categories' ] );Shortcode PHP function:
function shortcode_sitemap_categories( $attributes ) {
$atts = shortcode_atts(
[
'heading' => $this->options['sitemap_heading_type'],
'label' => $this->options['sitemap_categories'],
'no_label' => false,
'exclude' => '',
'exclude_tree' => '',
],
$attributes
);
$atts['heading'] = intval( $atts['heading'] ); // make sure it's an integer
if ( $atts['heading'] < 1 || $atts['heading'] > 6 ) { // h1 to h6 are valid
$atts['heading'] = $this->options['sitemap_heading_type'];
}
$html = '<div class="toc_sitemap">';
if ( ! $atts['no_label'] ) {
$html .= '<h' . $atts['heading'] . ' class="toc_sitemap_categories">' . htmlentities( $atts['label'], ENT_COMPAT, 'UTF-8' ) . '</h' . $atts['heading'] . '>';
}
$html .=
'<ul class="toc_sitemap_categories_list">' .
wp_list_categories(
[
'title_li' => '',
'echo' => false,
'exclude' => $atts['exclude'],
'exclude_tree' => $atts['exclude_tree'],
]
) .
'</ul>' .
'</div>';
return $html;
}
Code file location:
table-of-contents-plus/table-of-contents-plus/includes/class-toc-plus.phpTable of Contents Plus [sitemap_posts] Shortcode
‘Sitemap_posts’ is a shortcode that displays a list of all published posts. It sorts them in ascending order based on the title. It also includes an option to separate posts alphabetically. If set to ‘true’, it creates a new section for each alphabet letter.
Shortcode: [sitemap_posts]
Parameters
Here is a list of all possible sitemap_posts shortcode parameters and attributes:
order– determines the order of posts, ‘ASC’ for ascending, ‘DESC’ for descendingorderby– defines what parameter to sort posts by, ‘title’ for post titleseparate– if set to true, separates posts by the first letter of their title
Examples and Usage
Basic example – The shortcode ‘sitemap_posts’ can be used to generate a sitemap of all posts, sorted alphabetically by title in ascending order.
[sitemap_posts]Advanced examples
1. Display posts in descending order: You can alter the order of the posts by changing the ‘order’ attribute to ‘DESC’.
[sitemap_posts order="DESC"]2. Display posts ordered by date: You can also order the posts by date by changing the ‘orderby’ attribute to ‘date’.
[sitemap_posts orderby="date"]3. Display posts without separating them by the first letter of their title: By setting the ‘separate’ attribute to ‘false’, the posts will not be separated by the first letter of their title.
[sitemap_posts separate="false"]4. Combination of multiple parameters: You can also combine multiple parameters to customize the output. For example, to display posts in descending order by date without separating them by the first letter, you would use the following shortcode:
[sitemap_posts order="DESC" orderby="date" separate="false"]PHP Function Code
In case you have difficulties debugging what causing issues with [sitemap_posts] shortcode, check below the related PHP functions code.
Shortcode line:
add_shortcode( 'sitemap_posts', [ $this, 'shortcode_sitemap_posts' ] );Shortcode PHP function:
function shortcode_sitemap_posts( $attributes ) {
$atts = shortcode_atts(
[
'order' => 'ASC',
'orderby' => 'title',
'separate' => true,
],
$attributes
);
$articles = new WP_Query(
[
'post_type' => 'post',
'post_status' => 'publish',
'order' => $atts['order'],
'orderby' => $atts['orderby'],
'posts_per_page' => -1,
]
);
$html = '';
$letter = '';
$atts['separate'] = strtolower( $atts['separate'] );
if ( 'false' === $atts['separate'] || 'no' === $atts['separate'] ) {
$atts['separate'] = false;
}
while ( $articles->have_posts() ) {
$articles->the_post();
$title = wp_strip_all_tags( get_the_title() );
if ( $atts['separate'] ) {
if ( strtolower( $title[0] ) !== $letter ) {
if ( $letter ) {
$html .= '</ul></div>';
}
$html .= '<div class="toc_sitemap_posts_section"><p class="toc_sitemap_posts_letter">' . strtolower( $title[0] ) . '</p><ul class="toc_sitemap_posts_list">';
$letter = strtolower( $title[0] );
}
}
$html .= '<li><a href="' . get_permalink( $articles->post->ID ) . '">' . $title . '</a></li>';
}
if ( $html ) {
if ( $atts['separate'] ) {
$html .= '</div>';
} else {
$html = '<div class="toc_sitemap_posts_section"><ul class="toc_sitemap_posts_list">' . $html . '</ul></div>';
}
}
wp_reset_postdata();
return $html;
}
Code file location:
table-of-contents-plus/table-of-contents-plus/includes/class-toc-plus.phpConclusion
Now that you’ve learned how to embed the Table of Contents Plus Plugin shortcodes, understood the parameters, and seen code examples, it’s easy to use and debug any issue that might cause it to ‘not work’. If you still have difficulties with it, don’t hesitate to leave a comment below.
Leave a Reply