BuddyX
Get BuddyX Pro

Table of Contents

Pro feature

BuddyX Pro can add an automatic "On this page" list to the top of your single blog posts. It reads the headings you already wrote, turns each one into a jump link, and lets readers skip straight to the section they want. There is nothing to build by hand and no shortcode to place - you write your post with normal headings, flip one switch, and the theme does the rest.

What You Can Do

With the table of contents turned on, each qualifying single post gets:

  • An auto-generated list of its H2 and H3 headings, in the order they appear
  • A clickable jump link for every heading (smooth anchor navigation)
  • Numbered top-level entries (1, 2, 3...) with H3 subheadings nested underneath as a lettered list (a, b, c...)
  • Styling that follows your active Site Skin, border radius, and dark mode automatically

The list is generated on the server every time the post renders, so it always matches the current content. Edit a heading, add a section, reorder your H2s - the table of contents updates on the next page load with no extra step.

Turning It On

There is a single control for this feature.

  1. Go to Appearance > Customize
  2. Click on Blog
  3. Open the Single Post Settings section
  4. Find Show table of contents and set it to Yes
  5. Click Publish
Setting Control Default Options
Show table of contents (single_post_toc) On/off switch No (off) Yes / No

That is the only option. The feature is off by default, so existing sites look exactly the same until you enable it.

Tip: The table of contents applies to all single posts at once. It is a global toggle, not a per-post setting. If you need it on some posts but not others, see the "Common Questions" section below.

How It Works

Once the switch is set to Yes, BuddyX Pro does three things automatically when a single post loads:

  1. Adds anchors to your headings. Every H2 and H3 in the post gets an id derived from its text (for example, a heading called "Getting Started" becomes #getting-started). Headings that already have an id are left untouched.
  2. Builds the list. The theme scans the post for those H2 and H3 headings and assembles the "On this page" box.
  3. Places it at the top. The finished list is inserted at the very top of the post content, directly above your first paragraph.

The box is a proper <nav> list labelled "Table of contents" for screen readers, so it is keyboard reachable and accessible out of the box.

Which headings are included

Heading level In the table of contents? How it appears
H1 No Reserved for the post title
H2 Yes Top-level numbered entry
H3 Yes Nested lettered entry under its parent H2
H4 - H6 No Not listed

The heading levels are fixed at H2 and H3. This keeps the list focused on your main sections and their subsections, which is the level of detail readers actually scan. There is no control to add H4 or deeper - deeply nested lists become noise rather than navigation.

The two-heading minimum

Posts with fewer than two qualifying headings are skipped automatically. A table of contents with a single link tells the reader nothing, so BuddyX Pro simply does not render the box on those posts. This means you can safely leave the switch on for your whole site: short posts and heading-light posts stay clean, and only substantial posts get the navigation.

Where the Table of Contents Appears

The list always renders at the top of the post content, above the first paragraph and below the post title and featured image. This position is fixed - there is no setting to move it into a sidebar, pin it to the side, or make it float as the reader scrolls. It behaves as an inline "jump menu" at the start of the article, which is the pattern readers expect from a table of contents and which works identically on desktop and mobile.

Note: If you are looking for a floating or sticky progress indicator that follows the reader down the page, that is a separate feature - see the Reading Progress Bar in Single Post Settings.

Anchor Links Stay Stable

Each heading's anchor is generated from its text, so a link like yoursite.com/post/#installation points at your "Installation" heading. These anchors are stable as long as you do not rename the heading, which means you can share a deep link to a specific section - in an email, another post, or a support reply - and it keeps working across content edits. If you rename a heading, its anchor changes to match the new text, so update any external links that pointed at the old wording.

Styling and Dark Mode

The table of contents inherits your theme design - there are no separate colour pickers for it, by design. It draws from your active tokens:

  • A muted surface background with a subtle border
  • Your global Border Radius on the corners
  • Your Link colour for the entries, with a hover underline

Because it uses theme tokens rather than fixed colours, it repaints correctly when a visitor switches to dark mode and matches whatever Site Skin you have chosen. To restyle it beyond the defaults, target the .bx-toc class in Appearance > Customize > Additional CSS.

Best Used For

  • Long-form guides and tutorials (1500+ words with four or more sections)
  • Documentation, reference, and knowledge-base articles
  • Multi-step how-tos where a reader may want to jump straight to one step
  • Roundups and listicles with clearly headed sections

Skip It For

  • Short posts under 800 words (they rarely need in-page navigation)
  • News and opinion posts meant to be read top to bottom
  • Posts with one or no headings (the box will not render anyway)

Common Questions

I turned it on but no table of contents appears.

Check these in order:

  1. The post is a single post - the feature runs on single blog posts only, not on pages, archives, or custom post types.
  2. The post has at least two H2 or H3 headings - one heading is skipped by design.
  3. Your headings are real headings - text made bold or made large by hand is not a heading. Use the Heading block (or H2/H3 in the editor) so the theme can find them.
  4. Cache cleared - if you use a caching plugin, clear the cache and reload the post.

Can I show it on some posts but not others?

The customizer switch is global. Because posts with fewer than two headings are skipped automatically, the practical effect is that only your longer, well-structured posts display the box. If you need to suppress it on a specific long post, remove or reduce its headings, or add targeted CSS in Additional CSS using that post's body class.

Can I add H4 headings to the list?

No. The list is fixed to H2 and H3 to keep it scannable. H4 and deeper headings are ignored.

Can I move the table of contents into the sidebar or make it float?

Not through the customizer. It renders inline at the top of the content by design. Custom placement would require a child theme or custom development - reach out to us at support@wbcomdesigns.com if that is a hard requirement for your site.

Does it work with page builders?

The table of contents reads the standard post content that WordPress passes through the_content. Headings you place with the block editor or classic editor are detected. Content rendered entirely by a third-party builder that bypasses the normal content flow may not be scanned - test on one post before relying on it site-wide.

Related Settings

Got a question? We are a friendly team - happy to help.