Generate a Table of Contents for Your WordPress Post with PHP

Submitted by oretnom23 on Thursday, December 7, 2023 - 17:48.

In this tutorial, we will explore the creation of a custom PHP script for a WordPress website. The goal is to offer students and beginners a reference or guide to enhance their knowledge and skills in developing custom PHP scripts within WordPress. I'll be providing a simple snippet that generates an automated Table of Contents for post content.

What is the Purpose of Table of Contents in Website Content?

The purpose of a Table of Contents (TOC) in website content is to offer users a structured and organized navigation tool. It enhances website usability, facilitates navigation, and contributes to an improved overall user experience. This is particularly valuable for content-rich websites or lengthy articles.

How to Create an Auto-generated Table of Contents (TOC) in WordPress?

Below, I will provide a sample PHP script demonstrating an Auto-generated Table of Contents (TOC). Follow the steps outlined below:

Step 1: Add Custom Style

In your WordPress site theme, integrate the following Cascading Style Sheet (CSS) script below. This style defines the custom design for the Table of Contents.

.custom-toc-container {
    display: block;
    width: 100%;
    padding: 0.75em 1em;
    border: 1px solid #00000024;
    box-shadow: 2px 5px 5px #00000024;
    margin-bottom: 15px;
    border-radius: 7px;
}
.custom-toc-title {
    font-size: 1.5rem;
    letter-spacing: .8px;
    font-weight: 600;
    border-bottom: 1px solid #d3c9c9;
    padding-bottom: 10px;
    margin-bottom: 15px;
}
ul.custom-toc .custom-toc-item {
    padding: 3px 1px;
    list-style: square;
}
a.custom-toc-item {
    font-weight: 500;
    text-decoration: none;
}

Step 2: Add Custom PHP Script

WordPress provides a highly useful built-in filter hook called `the_content`. Utilizing this filter, we can modify the post content in WordPress before rendering it on the front end. To achieve this, open the `functions.php` file of your active WP Theme and add the custom PHP script with the mentioned filter, as shown below:

<?php 
/**
 * Generate Table of Contents
 */
function custom_content_toc($content){
    $new_content = $content;
    if(is_single()){
        $list = [];
        $ids = [];
        // Find all Headings from Content
        $headings = preg_match_all('/<h\d[^>]*>.*?<\/h\d>/si', $content, $matches);
        if($headings > 0 && isset($matches[0])){
            foreach($matches[0] as $k => $heading){
                // Getting the Heading Level
                preg_match_all('/<h(\d)[^>]*>/si', $heading, $level);
                $level = $level[1][0] ?? 1;
 
                //update heading attributes
                $id = "";
                $dom = new DOMDocument();
                $dom->loadHTML($heading);
                $html = new DOMXPath($dom);
                foreach($html->query('//h1 | //h2 | //h3 | //h4 | //h5') as $el){
                    // Get Heading ID
                    $id= $el->getAttribute('id') ?? '';
                    // Generate Heading ID if not exists
                    if(empty($id)){
                        $id = str_replace([" ",".",","], "-",trim(strtolower(strip_tags($heading))));
                    }
                    $i=1;
                    while(true){
                        if(!in_array($id, $ids)){
                            $ids[] = $id;
                            break;
                        }else{
                            $id = $id."_".($i++);
                        }
                    }
                    // Set Heading's Updated ID attribute
                    $el->setAttribute('id', $id);
                }
                $new_heading = $dom->saveHTML();
                $new_content = str_replace($heading, $new_heading, $new_content);
 
                $parent = false;
                // Locate and set the parent Heading
                if($level > 1 && !empty($list)){
                    $headingBeforeArr = array_slice($list, 0, $k + 1);
                    krsort($headingBeforeArr);
                    foreach($headingBeforeArr as $key => $headingBefore){
                        if($headingBefore['level'] < $level){
                            $parent = $key;
                            break;
                        }
                    }
                }
                // Add heading Item to array
                $list[] = ["level" => $level, "html" => $heading, "parent" => $parent, "id" => $id];
            }
        }
 
        /**
         * Generate the Table of Content 
         */
        $toc = "";
        if(!empty($list)){
            $toc .= "<div class='custom-toc-container'>";
            $toc .= "<div class='custom-toc-title'>Table of Contents</div>";
            $toc .= "<ul class='custom-toc'>";
            foreach($list as $k=> $row){
                if($row['parent'] !== false)
                    continue;
                $toc .= "<li class='custom-toc-item'>";
                $toc .= "<a href ='#{$row['id']}' class='custom-toc-item'>".(strip_tags($row['html']))."</a>";
                // Find Child Headings
                $toc .= get_child($list, $k);
                $toc .= "</li>";
            }  
            $toc .= "</ul>";
            $toc .= "</div>";
        }
 
    }
    // Return Post Content with Table of Contents 
    $new_content = $toc. $new_content;
    return $new_content;
}
 
/**
 * Generate Sub-Headings for Table of Contents
 */
function get_child($list = [], $parent = null){
    $child_content = "";
    if(!empty($list) && !is_null($parent)){
        foreach($list as $k => $row){
            if(!is_numeric($row['parent']) || $row['parent'] != $parent)
            continue;
                $child_content .= "<li class='custom-toc-item'>";
                $child_content .= "<a href ='#{$row['id']}' class='custom-toc-item'>".(strip_tags($row['html']))."</a>";
                $child_content .= get_child($list, $k);
                $child_content .= "</li>";
        }
    }
    if(!empty($child_content))
    $child_content = "<ul class='custom-toc'>{$child_content}</ul>";
    return $child_content;
}
 
add_filter( 'the_content' , 'custom_content_toc', 10, 1);
?>

Snapshots

Below are example snapshots utilizing the Custom CSS and PHP Script provided above to generate the Table of Contents for WordPress Posts:

WP Post without Table of Content

Table of Content UI

WP Post with Table of Content

There you have it! I trust that this Generate a Table of Contents for Your WordPress Post with PHP Tutorial proves beneficial for your needs and provides valuable insights for your future WordPress Website. Dive into more on this website for an array of Tutorials, Free Source Codes, and Articles covering various programming languages.

Consider exploring the following articles as well:

Happy Coding =)

Add new comment

140 views