AnchorKit Documentation

1. What Is AnchorKit?

AnchorKit is a modern, accessible, and feature-rich Table of Contents (TOC) plugin for WordPress with unparalleled customization options and developer-friendly architecture.

• Accessibility-First Design: WCAG 2.1 AA compliant with ARIA labels, keyboard navigation, and screen reader compatibility.
• Comprehensive Integration: Works seamlessly with Classic Editor, Gutenberg, Elementor, Divi, WPBakery Page Builder, and Visual Composer.
• Advanced Customization: 20+ shortcode attributes, 15+ developer hooks, extensive styling options, and granular control.
• Pro Features: Elementor widget, sticky TOC positions, reading-time metadata, ACF integration, AMP compatibility, and schema markup.
• Developer-Friendly: Extensive hooks and filters for complete customization without modifying core files.

Control AnchorKit globally via settings or override per-instance with Gutenberg blocks, Elementor widgets, shortcodes, and widgets.

2. Installation & Activation

1. Install the plugin:
   • From WordPress.org: search for "AnchorKit" in Plugins → Add New.
   • Or upload the ZIP via Plugins → Add New → Upload Plugin.
2. Activate AnchorKit in Plugins → Installed Plugins.
3. Go to Settings → AnchorKit to configure global settings.

For Pro features (Elementor widget, sticky TOC, ACF, AMP, etc.) you'll connect your license via Freemius. The UI works cleanly with or without Pro features active.

3. Quick Start (2‑Minute Setup)

1. Navigate to Settings → AnchorKit → Quick Start.
2. Turn "Table of Contents" on using the big toggle in the first card.
3. In "Where to Show":
   • Select the post types you want (e.g. Posts, Pages).
   • Leave Automatic Insertion enabled.
   • Choose a position: Before first heading (recommended), After first paragraph, Top of content, or Bottom of content.
4. Set Minimum Headings (default: 2). The TOC will only appear when the page has at least this many headings.
5. Choose which heading levels to include (e.g. H2–H4).
6. Pick a Style Preset (Minimal / Modern / Clean).
7. Save changes and view a post with several headings. You should see the TOC automatically inserted.

If you prefer manual placement, disable Automatic Insertion and use either the Gutenberg block, Elementor widget, sidebar widget, or comprehensive shortcode system [anchorkit_toc] with 20+ attributes.

4. Global Settings

All global settings live under Settings → AnchorKit. The interface is organized into tabs with extensive customization options.

4.1 Quick Start Tab

Activation

• Table of Contents toggle: Enables or disables the TOC site‑wide. When off, no TOC is rendered anywhere (including block/widget/shortcode), which is useful for debugging.

Where to Show

• Post Types: Choose which public post types should be eligible for a TOC (e.g. post, page, or custom post types).
• Automatic Insertion: When enabled, AnchorKit injects the TOC into the main content automatically on eligible post types.
• Position:
  • Before first heading – Inserts the TOC just before the first matching heading.
  • After first paragraph – Inserts TOC after the first <p>; works with Classic and block content.
  • Top of content – TOC appears at the very top.
  • Bottom of content – TOC appears at the bottom.
• Minimum Headings: Integer (1–10). If fewer headings than this are found, no TOC is displayed.

What to Include

• Heading Levels: Choose which heading levels AnchorKit will include (H1–H6). This affects both auto‑insert and shortcode when using global defaults.

Style Preset

• Minimal, Modern, Clean: Choose the base visual style for the TOC container. All presets are responsive, theme-aware, and accessibility-compliant.

Header Label

• Show/Hide TOC Title: Toggle the TOC heading (e.g. "Table of Contents").
• Title Text: Custom text for the TOC title.

4.2 Appearance & Behavior Tab

This tab controls how the TOC looks and behaves with comprehensive styling options.

Behavior

• Collapsible TOC: Allows users to collapse/expand the entire TOC with keyboard support.
• Initial State: Expanded or Collapsed on page load.
• Smooth Scrolling: Animated scroll when clicking TOC links with configurable easing.
• Scroll Offset: Pixel offset to account for sticky headers (e.g. 80–100px).
• Hierarchical View: Indents sub‑headings to reflect document structure with proper ARIA nesting.
• Show Numerals: Enables numbered lists for TOC items with various formats.
• Numbering Style & Format (Pro):
  • Style: Hierarchical (1.2.3) or Flat (1,2,3,…).
  • Format: decimal, decimal with leading zero, upper/lower Roman, upper/lower alpha.
  • Separator: dot, dash, or middle‑dot.

Styling

• Custom Styling: Override presets with custom colors, typography, spacing, and borders while maintaining accessibility standards.
• Colors (theme‑aware): Background, text, link, link hover, border, bullet, and active link colors for light and dark modes with high contrast options.
• Typography: Base font family, font size. (Pro: per-level sizes, line-height, letter-spacing, text transform).
• Spacing & Borders: Container padding, border width, border radius.
• Width & Float: Width %, Min/max width, Float left/right.

Pro‑Only Enhancements

• Sticky TOC: Position (Content, Left, Right), offset with smooth transitions.
• Back to Top Link: Inside TOC (when sticky) with accessibility features.
• Entrance Animations: fade, slide, zoom with reduced motion support.
• Scroll Easing & Duration customizable for better UX.
• View More: Show only N headings initially with expand/collapse functionality.
• Reading Time & Word Count: Per-section estimates with schema markup.

4.3 Structure & SEO Tab

Controls which content becomes part of the TOC and how anchors are generated with advanced filtering options.

Content Selection

• Include Headings: Duplicate of Quick Start; defines which heading tags are considered for TOC generation.
• Exclude Selectors: CSS selectors (e.g. .toc-exclude, #sidebar h2) to skip specific headings while maintaining accessibility.
• Exclude Keywords (Pro): Comma‑separated keywords to exclude headings containing them with case-insensitive matching.
• Trim Patterns (Pro): Patterns stripped from beginning of labels (e.g. "Chapter 1:", "Step 1:") with regex support.
• Heading Depth (Pro): Minimum and maximum heading depth to include with validation.

SEO & Anchors

• Anchor Format:
  • Auto – slugified heading text (#hello-im-a-heading) with Unicode support.
  • Sequential – numeric IDs (#section-1, #section-2) for predictable linking.
  • Custom Prefix – prefix + slug for branded anchor URLs.
• Custom Labels (JSON): Remap TOC labels without changing content headings for better UX.

{
  "Introduction": "Start Here",
  "FAQ": "Questions & Answers"
}

Schema Markup (Pro)

• Enable Schema.org: Output JSON‑LD markup describing the TOC as an ItemList for enhanced SEO.
• Schema Type: Article, BlogPosting, WebPage, HowTo, FAQPage, etc. with automatic detection.

4.4 Advanced & Accessibility Tab

• Hide on Mobile: Completely hide the TOC below a configurable breakpoint with responsive design.
• Mobile Breakpoint: Pixel width (default: 782px) with live preview.
• ARIA Label: Accessible label for the TOC <nav> element with internationalization support.
• Keyboard Navigation: Full keyboard support for all interactive elements.
• Screen Reader Support: Comprehensive ARIA implementation with live regions.
• Focus Management: Proper focus indicators and tab order.

4.5 Help & Pro Tabs

Access comprehensive documentation, developer resources, support forums, and Pro upgrade options.

5. Using AnchorKit in Different Contexts

5.1 Automatic Insertion (Global)

When enabled, AnchorKit parses the content, injects accessible IDs into headings, and inserts the TOC. It will not insert if disabled globally/automatically, if there are fewer headings than minimum, or if a manual TOC (block/shortcode/widget) is present to avoid duplication.

5.2 Gutenberg Block

Add the "Table of Contents (AnchorKit)" block. Options set in the block override global settings with live preview. All accessibility features and customization options are available.

5.3 Elementor Widget (Pro)

Search for "AnchorKit TOC" widget in Elementor. Configure Content, Behavior, Pro Features, and Styles visually with drag-and-drop controls. Each widget instance can override global settings.

5.4 Sidebar Widget

Add the "AnchorKit TOC" widget via Appearance → Widgets. Perfect for sidebar placement with sticky positioning options. Only appears on singular posts/pages.

5.5 Shortcode System

Use the comprehensive shortcode system [anchorkit_toc] with 20+ attributes for complete control. See the Shortcode System section below for full documentation.

6. Shortcode System

AnchorKit features the most comprehensive shortcode system available, with 20+ attributes for granular control over TOC generation and display.

6.1 Basic Usage

[anchorkit_toc]

6.2 Advanced Examples

Custom Display Control

[anchorkit_toc header_label="Contents" display_header_label="yes" toggle_view="no" initial_view="hide"]

Content Filtering

[anchorkit_toc heading_levels="2,3,4" exclude="Test" post_types="post,page" post_in="1,2,3" min_headings="3"]

Appearance & Styling

[anchorkit_toc display_counter="yes" theme="dark" preset="modern" class="my-custom-toc"]

Behavior & Accessibility

[anchorkit_toc hierarchical="yes" smooth_scroll="no" device_target="mobile"]

Pro Features

[anchorkit_toc sticky="yes" show_reading_time="yes" view_more="5" show_word_count="yes"]

6.3 Complete Attribute Reference

Display Control

• header_label="Title" - Custom TOC title
• display_header_label="no" - Hide title
• toggle_view="no" - Disable collapsible toggle
• initial_view="hide" - Start collapsed

Content Filtering

• heading_levels="2,3" - Include only H2 and H3 headings
• exclude="Test" - Exclude headings containing "Test"
• post_types="post,page" - Limit to specific post types
• post_in="1,2" - Include only specific post IDs
• post_not_in="1,2" - Exclude specific post IDs
• min_headings="3" - Require minimum number of headings

Appearance

• display_counter="yes" - Enable numbered lists
• class="custom-toc" - Add custom CSS class
• theme="dark" - Set theme (system/light/dark)
• preset="modern" - Choose style preset

Behavior

• hierarchical="yes" - Enable nested sub-headings
• smooth_scroll="no" - Disable smooth scrolling
• device_target="mobile" - Show only on mobile/desktop

Pro Features

• view_more="5" - Show only first 5 headings initially
• sticky="yes" - Enable sticky positioning
• show_reading_time="yes" - Display reading time
• show_word_count="yes" - Display word counts

6.4 ACF Integration (Pro)

[anchorkit_toc acf_enabled="yes" acf_merge_mode="after" acf_field_names="content,additional_content"]

• acf_enabled="yes" - Enable ACF field integration
• acf_merge_mode="before/after/replace" - How to merge ACF content
• acf_field_names="field1,field2" - ACF field names to include

7. Integrations

7.1 Advanced Custom Fields (ACF) (Pro)

Includes headings from ACF WYSIWYG/text/textarea fields. Configure field names globally or per-instance with flexible merge modes.

7.2 AMP Compatibility (Pro)

Automatically detects AMP pages and outputs AMP-safe markup. Custom JavaScript behavior is disabled on AMP while maintaining full functionality.

7.3 Page Builders

Full compatibility with:

• Gutenberg - Native block with live preview
• Elementor - Dedicated widget with visual controls
• Divi - Shortcode integration
• WPBakery - Shortcode support
• Visual Composer - Full compatibility

7.4 Translation Plugins

Works seamlessly with WPML, Polylang, and other translation plugins with full internationalization support.

8. Troubleshooting

8.1 When the TOC Will Not Appear

1. TOC is disabled globally: Check Quick Start settings.
2. Post type not allowed: Check "Show on" settings.
3. Not enough headings: Must meet Minimum Headings count.
4. Manual TOC present: Auto-insertion is skipped if a block, shortcode, or widget is already used.
5. Other TOC plugins: Disable competing plugins like Easy TOC.
6. Theme conflicts: Check for CSS conflicts or JavaScript errors.
7. Shortcode attributes: Verify attribute names and values are correct.

8.2 Common Issues

• Shortcode not working: Ensure the plugin is active and shortcode is properly formatted.
• Styling issues: Check for theme CSS conflicts or use custom class attribute.
• Accessibility warnings: Ensure proper heading hierarchy in content.
• Mobile display: Check device_target and mobile breakpoint settings.
• Performance: Enable caching and minify assets for production.

9. Developer Hooks & Customization

AnchorKit includes 15+ WordPress-style hooks and filters for complete programmatic customization without modifying core files.

9.1 Understanding the Context Array

All hooks receive a context array with information about how and where the TOC is being rendered:

[
    'source' => 'auto_insertion' | 'shortcode' | 'gutenberg_block' | 'elementor_widget' | 'widget',
    'post_id' => 123,
    'is_admin' => false,
    'data' => [ /* source-specific metadata */ ],
    'render_settings' => [ /* processed settings */ ],
]

9.2 High Priority Hooks

Control TOC Visibility

add_filter( 'anchorkit_should_display_toc', function ( $should_display, $post_id, $headings ) {
    // Hide TOC on specific post types
    if ( get_post_type( $post_id ) === 'product' ) {
        return false;
    }
    // Hide TOC on posts with "no-toc" in title
    if ( stripos( get_the_title( $post_id ), 'no-toc' ) !== false ) {
        return false;
    }
    return $should_display;
}, 10, 3 );

Customize Anchor IDs

add_filter( 'anchorkit_anchor_id', function ( $anchor, $text, $format ) {
    // Add custom prefix to all anchors
    return 'section-' . $anchor;
}, 10, 3 );

Control Heading Requirements

add_filter( 'anchorkit_min_headings', function ( $min_headings, $post_id ) {
    // Require only 1 heading for pages
    if ( get_post_type( $post_id ) === 'page' ) {
        return 1;
    }
    return $min_headings;
}, 10, 2 );

Filter Post Types

add_filter( 'anchorkit_post_types', function ( $post_types ) {
    // Add custom post type support
    $post_types[] = 'portfolio';
    $post_types[] = 'case_study';
    return $post_types;
}, 10, 1 );

Exclude Specific Posts

add_filter( 'anchorkit_exclude_post', function ( $exclude, $post_id ) {
    // Exclude specific posts by ID
    $excluded_ids = [ 123, 456, 789 ];
    if ( in_array( $post_id, $excluded_ids ) ) {
        return true;
    }
    return $exclude;
}, 10, 2 );

9.3 Medium Priority Hooks

Customize TOC Title

add_filter( 'anchorkit_title_text', function ( $title_text, $context ) {
    // Add emoji and context-specific text
    if ( $context['source'] === 'widget' ) {
        return '📑 ' . $title_text;
    }
    return '📚 ' . $title_text;
}, 10, 2 );

Modify Heading Display

add_filter( 'anchorkit_heading_text', function ( $text, $heading, $context ) {
    // Truncate long headings
    if ( strlen( $text ) > 50 ) {
        return substr( $text, 0, 47 ) . '...';
    }
    // Remove common prefixes
    $text = preg_replace( '/^(Step|Chapter)\s+\d+:\s*/i', '', $text );
    return $text;
}, 10, 3 );

Filter Content Before Processing

add_filter( 'anchorkit_content_to_parse', function ( $content, $post_id ) {
    // Add custom content for heading extraction
    $custom_content = get_post_meta( $post_id, 'additional_content', true );
    if ( ! empty( $custom_content ) ) {
        $content .= "\n\n" . $custom_content;
    }
    return $content;
}, 10, 2 );

Adjust Smooth Scroll Offset

add_filter( 'anchorkit_smooth_scroll_offset', function ( $offset ) {
    // Increase offset for sticky headers
    return $offset + 50;
}, 10, 1 );

9.4 Rendering Hooks

Modify Headings Array

add_filter( 'anchorkit_toc_headings', function ( $headings, $context ) {
    // Remove headings containing "sponsored"
    return array_filter( $headings, function ( $heading ) {
        return stripos( $heading['text'], 'sponsored' ) === false;
    } );
}, 10, 2 );

Customize Container Classes

add_filter( 'anchorkit_toc_container_classes', function ( $classes, $context ) {
    // Add context-specific classes
    if ( $context['source'] === 'widget' ) {
        $classes[] = 'toc-sidebar';
    } elseif ( $context['source'] === 'elementor_widget' ) {
        $classes[] = 'toc-elementor';
    }
    // Add custom theme classes
    $classes[] = 'my-theme-toc';
    return $classes;
}, 10, 2 );

Modify Final HTML Output

add_filter( 'anchorkit_toc_html', function ( $html, $context ) {
    // Add custom wrapper for specific contexts
    if ( $context['source'] === 'shortcode' ) {
        return '<div class="custom-toc-wrapper">' . $html . '</div>';
    }
    return $html;
}, 10, 2 );

Customize Link Attributes

add_filter( 'anchorkit_toc_link_attributes', function ( $attrs, $heading, $context ) {
    // Add custom attributes for analytics
    $attrs['data-heading-level'] = $heading['level'];
    $attrs['data-toc-source'] = $context['source'];

    // Add rel attribute for external links (if applicable)
    if ( strpos( $heading['text'], 'external' ) !== false ) {
        $attrs['rel'] = 'noopener noreferrer';
        $attrs['target'] = '_blank';
    }

    return $attrs;
}, 10, 3 );

Inject Content Before TOC

add_action( 'anchorkit_toc_before', function ( $context ) {
    // Add introductory text
    echo '<p class="toc-intro">Jump to any section:</p>';

    // Add breadcrumb navigation for pages
    if ( $context['source'] === 'auto_insertion' && is_page() ) {
        echo '<nav aria-label="Breadcrumb">...</nav>';
    }
} );

Inject Content After TOC

add_action( 'anchorkit_toc_after', function ( $context ) {
    // Add call-to-action
    echo '<p class="toc-cta"><a href="#comments">Leave a comment</a></p>';

    // Add social sharing for posts
    if ( $context['source'] === 'auto_insertion' && is_single() ) {
        echo '<div class="social-share">...</div>';
    }
} );

9.5 Best Practices

• Use appropriate priorities: Early hooks (1-5) for filtering, later hooks (10+) for modification.
• Check context: Use the context array to apply changes only where needed.
• Maintain accessibility: Preserve ARIA labels and semantic structure when modifying HTML.
• Test thoroughly: Check your customizations across different contexts and devices.
• Document your code: Comment custom hooks for future maintenance.

9.6 Example Plugin

Create a custom plugin to house your AnchorKit customizations:

<?php
/**
 * Plugin Name: My AnchorKit Customizations
 * Description: Custom hooks and filters for AnchorKit
 * Version: 1.0.0
 */

add_filter( 'anchorkit_anchor_id', function ( $anchor, $text, $format ) {
    return 'my-prefix-' . $anchor;
}, 10, 3 );

add_filter( 'anchorkit_toc_container_classes', function ( $classes, $context ) {
    $classes[] = 'my-custom-toc';
    return $classes;
}, 10, 2 );
?>