Knowledge Byte #6 - What's in an article? Well, ask the Table of contents

[Lucas Vieites]

If you are a regular reader of this community, you may have seen previous posts about text editor features, like code blocks and lists. Today's topic is the Table of contents (TOC).

This feature is represented by this icon: 

When you start a new document, the icon will be greyed out and disabled. This is because it relies on specific HTML tags in your text to build the content list; the HTML headings. If you are familiar with HTML, these are the <h1>, <h2>, ... <h6> tags that you can use to organise your content.

You can mark a piece of text as a heading by putting your cursor in the text (no need to have it selected) and using the Paragraph toolbar item to set the heading level. You can choose from 6 levels, and you might want to check if there are any recommendations from your Knowledge Management team regarding which level you should start at. It's common to use the top-level (<H1>) for page titles, which then means you should use the second level (<H2>) as the starting point in your KB article. This affects how search engines read and store your content (SEO).

Take, for example, the following piece of sample text:

This is the main header of this article (H2)

More about headers (H3)

Headers (or headings) are the most simple and easy way to divide the content of a piece of text. The HTML language provides 6 standard levels of headings, from H1 to H6.

What is H2? (H4)

The H2 tag is the second level

What is H3? (H4)

The H3 tag is the third level

Additional Information (H3)

• HTML headings at w3schools
• Another tutorial at Tutorial Republic

I put the heading level in parenthesis after each section so you can see what it will look like in the TOC.

To create the TOC you simply have to locate your cursor where you want it in the text (usually at the top) and select the toolbar button. You will see that a new section appears:

Note that, in this example, only heading levels 2 and 3 are present in the TOC. This is the default behavior; it will only scan three levels deep and, because I didn't use H1, it will only include the H2 and H3 headings. This is currently not configurable.

The coolest part is that, whenever you update your article and add or remove sections with headings, you can refresh the TOC by clicking inside it and then clicking on the Refresh icon that appears. The internal links will be updated automatically.

I hope that this will help you improve your ServiceNow KB articles. Do let me know if you get stuck in the process, or if you think I missed something.

---

The Knowledge Bytes series are quick tips that can help you create better knowledge base articles. Read them all in the Knowledge Managers on ServiceNow!