How to Add a Table of Contents to Knowledge Base Articles

A table of contents helps visitors move around longer knowledge base articles without having to scroll through the whole page.

SoftwareRoad Knowledge Base can build the table of contents automatically from the headings used inside your article.

How the table of contents works

The plugin looks for headings inside the article and turns them into clickable links.

It can use:

• Heading 2
• Heading 3
• Heading 4

When a visitor selects one of the links, the page moves to that part of the article.

You do not need to create the links manually.

Enable the article table of contents

To enable it:

1. Sign in to your WordPress dashboard.
2. Open Knowledge Base > Settings.
3. Select the Articles or Features tab.
4. Find the article table of contents option.
5. Enable it.
6. Choose where it should appear.
7. Select Save Changes.

Open one of your longer articles afterwards to check the result.

Choose where the table of contents appears

SoftwareRoad Knowledge Base can display the article table of contents in different positions.

Depending on your settings, you can place it:

• Above the article content
• In the right-hand article sidebar

Choose the position that works best with your article layout.

Table of contents above the article

Displaying the table of contents above the main content makes it immediately visible.

This works well when:

• The article is long
• Visitors may want to jump straight to a section
• The page does not use a sidebar
• The article is viewed regularly on mobile devices

The table of contents will appear before the main article instructions.

Table of contents in the sidebar

The sidebar position keeps the table of contents beside the article on larger screens.

This works well when:

• The article uses a right-hand sidebar
• You want the main content area to remain clean
• Visitors need to move between several sections
• The headings are short enough to fit comfortably

On smaller screens, the sidebar may move underneath or above the main content depending on the layout.

Always check the article on a phone after enabling this option.

Change the table of contents heading

You can change the heading shown above the links.

Examples include:

• Table of Contents
• In This Article
• On This Page
• Jump to a Section
• What This Guide Covers
• Article Contents

Choose wording that matches the tone of your documentation.

In This Article often feels a little more natural, while Table of Contents is clear and familiar.

Add headings to an article

The table of contents will only appear when the article contains suitable headings.

To add one in the WordPress editor:

1. Open Knowledge Base > All Articles.
2. Edit the article.
3. Add a Heading block.
4. Choose Heading 2, Heading 3 or Heading 4.
5. Enter the heading text.
6. Update the article.

The heading should then be added to the table of contents automatically.

Use Heading 2 for main sections

Heading 2 should be used for the main parts of the article.

For example:

• Before You Begin
• Install the Plugin
• Activate the Licence
• Create the Knowledge Base Page
• Fix Common Problems

These are the main sections visitors are most likely to jump to.

Use Heading 3 for smaller sections

Heading 3 should be used underneath a Heading 2.

For example:

• Heading 2: Fix Common Problems
  • Heading 3: The Licence Is Not Recognised
  • Heading 3: The Licence Server Cannot Be Reached
  • Heading 3: The Activation Screen Keeps Appearing

This gives the table of contents a clear structure.

Use Heading 4 carefully

Heading 4 can be used for smaller points inside a Heading 3 section.

Most articles will not need many Heading 4 headings.

Using too many levels can make the table of contents feel cluttered, especially on smaller screens.

For most knowledge base articles, Heading 2 and Heading 3 will be enough.

Do not use Heading 1 inside the article

The article title normally acts as the page’s main Heading 1.

Avoid adding another Heading 1 inside the article content.

Start the main article sections with Heading 2.

This gives the page a clearer structure for visitors and search engines.

Write clear headings

Each heading should tell visitors what the section covers.

Good examples include:

• How to Activate the Licence
• Where to Find Your Product Key
• Change the Knowledge Base Colours
• Fix Article 404 Errors
• Remove a Category Image

Avoid vague headings such as:

• More Information
• Other
• Important
• Next
• Details

A visitor should be able to scan the table of contents and understand what each section contains.

Keep headings fairly short

Long headings can make the table of contents difficult to read.

For example:

What you should do if the licence activation page continues appearing after you have entered your details

could be shortened to:

Fix the Activation Page Appearing Again

The shorter version is easier to scan while still explaining the section.

Use a sensible heading order

Headings should follow a logical structure.

For example:

• Heading 2
  • Heading 3
  • Heading 3
• Heading 2
  • Heading 3

Avoid jumping from Heading 2 straight to Heading 4 unless there is a good reason.

A clear structure helps both the article and the table of contents make sense.

Avoid using headings only for styling

Do not use heading blocks simply because you want text to look larger or bolder.

Headings should describe actual sections of the article.

If you only need bold text, use bold formatting inside a normal paragraph.

Using unnecessary headings can fill the table of contents with text that does not belong there.

Check the generated links

After updating the article:

1. Open the public article page.
2. Find the table of contents.
3. Select each link.
4. Confirm that the page moves to the correct heading.
5. Check the link order.
6. Test the article on mobile.

The links are generated automatically from the article headings.

What happens when a heading is changed?

If you rename a heading, the table of contents will use the new wording after the article is updated.

The link connected to that heading may also change.

If someone has shared a direct link to a particular article section, changing the heading could affect that section link.

For normal knowledge base use, this is unlikely to cause a problem, but it is worth remembering for heavily shared guides.

What happens when a heading is removed?

If you delete a heading from the article and update it, the matching table of contents link should also disappear.

If the old link remains visible, clear your website cache and reload the page.

Use the table of contents for longer articles

A table of contents is most useful when an article contains several sections.

It may not add much value to a short guide with only one or two headings.

You can still leave the feature enabled globally. Short articles without enough headings may simply show no table of contents.

Avoid making the table too long

A table of contents with dozens of links can become difficult to use.

If an article contains too many sections, consider whether it should be split into several separate guides.

For example, one very long article covering installation, activation, design, analytics and troubleshooting may be easier to manage as several focused articles.

Shorter articles are often easier to read, search and update.

Table of contents and article search

The table of contents does not replace knowledge base search.

Search helps visitors find the right article.

The table of contents helps them move around once they are inside that article.

Using both gives visitors a quicker way to find the exact information they need.

Table of contents and the article sidebar

If the table of contents is shown in the sidebar, avoid adding too many other sidebar sections above it.

A busy sidebar could include:

• Compact search
• Table of contents
• Popular Articles
• Related Articles
• Help box

Choose the most useful sections and keep the page easy to scan.

For a long guide, placing the table of contents near the top of the sidebar usually makes sense.

Check sticky or fixed behaviour

Depending on the current article layout, the sidebar may remain visible while the visitor scrolls.

Check that the table of contents does not cover other page content or extend beyond the screen.

A very long list may not work well inside a fixed sidebar.

Shortening headings or moving the table above the article can help.

The table of contents is not showing

If the table of contents is missing, check that:

• The feature is enabled
• The article contains Heading 2, Heading 3 or Heading 4 blocks
• The article is published
• The correct display position is selected
• The settings were saved
• The website cache has been cleared
• Your SoftwareRoad Knowledge Base licence is active

Try adding two simple Heading 2 blocks to the article and update it again.

Headings are missing from the table

If only some headings appear, check that the missing text is using a real WordPress Heading block.

Bold paragraph text will not be recognised as a heading.

Edit the block and confirm that it is set to:

• H2
• H3
• H4

Then update the article and clear the cache.

The table includes text that should not be there

If unwanted text appears, it has probably been added using a Heading block.

Change that block back to a normal Paragraph block if it is not a genuine article section.

Update the article and check the table again.

The links do not move to the right section

If a table of contents link does not work correctly:

1. Update the article again.
2. Clear the WordPress cache.
3. Clear any hosting or server cache.
4. Test while signed out of WordPress.
5. Check for duplicate headings.
6. Check whether another script is changing the page links.

Using several identical headings may make section links harder to distinguish.

Try giving each heading unique wording.

The table looks too crowded

If the table contains too many links:

• Shorten the headings
• Remove unnecessary Heading 4 sections
• Combine very small sections
• Move the table into the sidebar
• Split the article into separate guides

The table should make the article easier to use, not give visitors another long list to work through.

The sidebar table is too narrow

Long heading text may wrap onto several lines inside a narrow sidebar.

You can improve this by:

• Shortening the headings
• Using fewer heading levels
• Choosing the above-content position
• Checking the article page width
• Removing an additional theme sidebar

SoftwareRoad Knowledge Base normally works best when the article has enough space for both the main content and its own sidebar.

Check the table of contents on mobile

On a mobile device, make sure that:

• The table is easy to find
• Links are easy to tap
• Long headings wrap neatly
• The table does not take over the whole screen
• Selecting a link moves to the correct section
• The heading is not hidden underneath a fixed website header

If the sidebar version feels awkward on mobile, the above-content position may work better.

Table of contents checklist

Before finishing, check that:

• The feature is enabled
• The display position suits the article layout
• The table heading is clear
• Main sections use Heading 2
• Smaller sections use Heading 3
• Heading 4 is only used when needed
• No extra Heading 1 blocks are used
• Headings are short and descriptive
• Every link moves to the correct section
• The layout works on desktop and mobile
• The table does not make the article feel overcrowded

Your article table of contents is now ready to help visitors move quickly between sections.