roi-theme/wp-content/themes/apus-theme/inc/toc.php

<?php
/**
 * Table of Contents (TOC) Functions
 *
 * This file contains functions to automatically generate a table of contents
 * from post content headings (H2 and H3).
 *
 * @package Apus_Theme
 * @since 1.0.0
 */

// Exit if accessed directly
if (!defined('ABSPATH')) {
    exit;
}

/**
 * Extract headings from post content
 *
 * Parses the content and extracts all H2 and H3 headings with their text.
 *
 * @param string $content Post content
 * @return array Array of headings with level, text, and ID
 */
function apus_extract_headings($content) {
    if (empty($content)) {
        return array();
    }

    $headings = array();

    // Match H2 and H3 tags with their content
    preg_match_all('/<h([23])(?:[^>]*)>(.*?)<\/h\1>/i', $content, $matches, PREG_SET_ORDER);

    foreach ($matches as $index => $match) {
        $level = (int) $match[1]; // 2 or 3
        $text = strip_tags($match[2]); // Remove any HTML tags inside heading

        // Generate a clean ID from the heading text
        $id = apus_generate_heading_id($text, $index);

        $headings[] = array(
            'level' => $level,
            'text'  => $text,
            'id'    => $id,
        );
    }

    return $headings;
}

/**
 * Generate a clean ID for a heading
 *
 * Creates a URL-friendly ID from heading text.
 *
 * @param string $text Heading text
 * @param int $index Index of the heading (for uniqueness)
 * @return string Clean ID
 */
function apus_generate_heading_id($text, $index) {
    // Remove special characters and convert to lowercase
    $id = sanitize_title($text);

    // If ID is empty, use a fallback
    if (empty($id)) {
        $id = 'heading-' . $index;
    }

    return $id;
}

/**
 * Generate HTML for Table of Contents
 *
 * Creates a nested list structure from the headings array.
 *
 * @param array $headings Array of headings from apus_extract_headings()
 * @return string HTML for the table of contents
 */
function apus_generate_toc($headings) {
    if (empty($headings) || count($headings) < 2) {
        return ''; // Don't show TOC if there are fewer than 2 headings
    }

    $toc_html = '<nav class="apus-toc" aria-label="' . esc_attr__('Table of Contents', 'apus-theme') . '">';
    $toc_html .= '<div class="apus-toc-header">';
    $toc_html .= '<h2 class="apus-toc-title">' . esc_html__('Table of Contents', 'apus-theme') . '</h2>';
    $toc_html .= '<button class="apus-toc-toggle" aria-expanded="true" aria-controls="apus-toc-list">';
    $toc_html .= '<span class="toggle-icon" aria-hidden="true"></span>';
    $toc_html .= '<span class="screen-reader-text">' . esc_html__('Toggle Table of Contents', 'apus-theme') . '</span>';
    $toc_html .= '</button>';
    $toc_html .= '</div>';

    $toc_html .= '<ol class="apus-toc-list" id="apus-toc-list">';

    $current_level = 2;
    $open_sublists = 0;

    foreach ($headings as $index => $heading) {
        $level = $heading['level'];
        $text = esc_html($heading['text']);
        $id = esc_attr($heading['id']);

        // Handle level changes
        if ($level > $current_level) {
            // Open nested list for H3
            $toc_html .= '<ol class="apus-toc-sublist">';
            $open_sublists++;
        } elseif ($level < $current_level && $open_sublists > 0) {
            // Close nested list when going back to H2
            $toc_html .= '</li></ol></li>';
            $open_sublists--;
        } elseif ($index > 0) {
            // Close previous item
            $toc_html .= '</li>';
        }

        $toc_html .= '<li class="apus-toc-item apus-toc-level-' . $level . '">';
        $toc_html .= '<a href="#' . $id . '" class="apus-toc-link">' . $text . '</a>';

        $current_level = $level;
    }

    // Close any open lists
    $toc_html .= '</li>';
    while ($open_sublists > 0) {
        $toc_html .= '</ol></li>';
        $open_sublists--;
    }

    $toc_html .= '</ol>';
    $toc_html .= '</nav>';

    return $toc_html;
}

/**
 * Add IDs to headings in content
 *
 * Modifies the post content to add ID attributes to H2 and H3 headings.
 *
 * @param string $content Post content
 * @return string Modified content with IDs added to headings
 */
function apus_add_heading_ids($content) {
    if (empty($content)) {
        return $content;
    }

    // Extract headings first to get consistent IDs
    $headings = apus_extract_headings($content);

    if (empty($headings)) {
        return $content;
    }

    // Replace headings with versions that include IDs
    $heading_index = 0;
    $content = preg_replace_callback(
        '/<h([23])(?:[^>]*)>(.*?)<\/h\1>/i',
        function($matches) use ($headings, &$heading_index) {
            if (!isset($headings[$heading_index])) {
                return $matches[0];
            }

            $level = $matches[1];
            $text = $matches[2];
            $id = $headings[$heading_index]['id'];
            $heading_index++;

            return '<h' . $level . ' id="' . esc_attr($id) . '">' . $text . '</h' . $level . '>';
        },
        $content
    );

    return $content;
}

/**
 * Display Table of Contents before post content
 *
 * Hooks into apus_before_post_content to display TOC on single posts.
 */
function apus_display_toc() {
    // Only show on single posts
    if (!is_single()) {
        return;
    }

    global $post;

    if (empty($post->post_content)) {
        return;
    }

    // Extract headings from content
    $headings = apus_extract_headings($post->post_content);

    // Generate and display TOC
    $toc = apus_generate_toc($headings);

    if (!empty($toc)) {
        echo $toc; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Escaped in apus_generate_toc()
    }
}
add_action('apus_before_post_content', 'apus_display_toc');

/**
 * Modify post content to add heading IDs
 *
 * Filters the_content to add IDs to headings for TOC linking.
 *
 * @param string $content Post content
 * @return string Modified content
 */
function apus_filter_content_add_heading_ids($content) {
    // Only apply to single posts
    if (!is_single()) {
        return $content;
    }

    return apus_add_heading_ids($content);
}
add_filter('the_content', 'apus_filter_content_add_heading_ids', 10);