Create an article table of contents (TOC) from headers

For long articles, you may want to create create a table of contents inside your articles with links to different sections of content. Rather than use manually-created anchors, you can save a bunch of time on setup by using one of our snippets.

We have two snippets for you to use: one will create a table of contents using a single level of headings (Heading 2). The other will create a nested table of contents using several levels of headings (Heading 2, Heading 3, and Heading 4). This article demonstrates the nested table of contents.

How to use the snippets

Using one of these snippets will create a clickable table of contents in list format that links to either all of the Heading 2s in your article, or all of the Headings in the levels you specify in the article. You can place the snippet wherever you would like the table of contents to appear:

Sample usage of the article TOC snippet

If you'd like to apply the article table of contents snippet to all articles in your knowledge base, you can add it to the Custom HTML for article:

1. Go to Settings > Style.
2. Click on Custom HTML and select Article from the dropdown.
3. Add the snippet mergecode in where you'd like it to appear. For example, adding it here will place it after the article title and Last Modified line but before the start of the article's text itself: Include the snippet in your Article Custom HTML to apply it to every article in your knowledge base

4. Click Save.

Snippet 1: Article TOC with one level of headings

This snippet will create a table of contents listing all of the headings of a specific level (by default, the snippet uses Heading 2, but you can edit this to suit your style guide.) You can see this snippet in action in Working with Anchors.

To use this snippet:

1. Go to Library > Snippets.
2. Click on Create New Snippet.
3. Give your Snippet a name and a merge code, and choose to hide it from PDFs (since it won't work in this format).
4. Change the editor type to 'Code Editor' first (instead of the WYSIWYG one) and then copy and paste the following code into the Snippet text area:

   <script id="snippet-prepend">
   $(function(){
     //Set the title for TOC. Can change h4 tags and text between them to change the text.
     //For no title, use: "<nav role='navigation' class='table-of-contents toc-top'><ul>";
     var ToC = "<nav role='navigation' class='table-of-contents toc-top'><h4>In this article:</h4><ul>";
     var el, title, link;
     //Grab all the H2s and turn them into TOC titles. Adjust h2 in first line to use a different header level
     $(".hg-article-body h2").each(function() {
       el = $(this);
       // If 'Header anchors' are enabled, the anchor we need will already be there
       if(el.hasClass('ko-header-anchor')) {
         title = el.text().slice(0, -1); // get rid of trailing # caused by existing anchor
         link = el.find('.ko-anchor-icon').attr('name');
       } else {
         title = el.text();
         el.addClass('toc-anchor-target')
         anchorTitle = el.text().replace(/([~!@"#$%^&*()_+=`{}\[\]\|\\:;'<>,.\/\? ])+/g, '-').toLowerCase().trim();
         link = "#" + anchorTitle;
         el.html('<a id="'+anchorTitle+'" class="toc-anchor"></a>' + el.html());
       }
   
       newLine =
         "<li>" +
           "<a class='article-anchor' href='" + link + "'>" +
             title +
           "</a>" +
         "</li>";
   
       ToC += newLine;
     });
   
     ToC +="</ul></nav>";
     // only add the Article TOC if there are headers
     if($(".hg-article-body h2").length > 0) {
       $("#snippet-prepend").before(ToC);
     }
   });
   </script>
   
   <style>
   /* Styles for Article TOC snippet to work*/
   /* .toc-top styles the box for the TOC; adjust styles here to tweak look and feel */
   .toc-top {
     background-color: #f5f5f5; /* set to #fff or delete entirely for no background */
     border: 1px solid #e3e3e3; /* adjust the color hex here to change border color */
     border-radius: 4px;
     box-shadow: 0 1px 1px rgba(0, 0, 0, 0.05) inset;
     margin-bottom: 20px;
     min-height: 20px;
     padding: 5px 30px;
   }
   .toc-anchor-target {
     scroll-margin-top: 100px;
   }
   .toc-anchor { 
     visibility: hidden;
   }
   </style>

   Your final snippet should look something like this when you save it: Sample Article TOC snippet using H2s
5. Click Create.
6. Copy and paste the merge code for your snippet into any article where you want the table of contents to appear, as shown in the Editor screenshot at the top of this article.

Customize the Table of Contents header/wording

You can tweak this code to customize the appearance and functionality of your Article Table of Contents.

• Customize the Table of Contents header text. Replace "In this article:" with wording of your choice in row 7:

  "<nav role='navigation' class='table-of-contents toc-top'><h4>Quick Links</h4>" + "<ul>";

• Change the "In this article" text from an h4 to a div, p, or any other HTML element in row 7. Or remove it. Here, we've changed it to paragraph:

  "<nav role='navigation' class='table-of-contents toc-top'><p>In this article:</p>" + "<ul>";

• Customize the script to build the table of contents of header 3s instead of header 2s in row 10: 

     $(".hg-article-body h3").each(function() {

Snippet 2: Article TOC with nested headers

This snippet will create a table of contents with nested/bullet point headings for multiple layers of headings. By default, the snippet uses Headings 2, 3, and 4 but you can edit these. You can see this snippet in action if you go back to the top.

To use this snippet:

1. Go to Library > Snippets.
2. Click on Create New Snippet.
3. Give your Snippet a name and a merge code, and choose to hide it from PDFs (since it won't work in this format). 
4. Change the editor type to 'Code Editor' first (instead of the WYSIWYG one) and then copy and paste the following code into the Snippet text area:

5. <script id="snippet-prepend">
   $(function(){
   
        var ToC =
     "<nav role='navigation' class='table-of-contents toc-top'><h4>In this article:</h4>" + "<ul>";
        var el,     title, link, header;
         //Define the heading levels you want to use in ascending order. Can add extra or remove unneeded.
        $(".hg-article-body h2, .hg-article-body h3, .hg-article-body h4").each(function() {
                 el = $(this);
                 title = el.text();
                    if(title != ''){
                   anchorTitle = el.text().replace(/([~!@"#$%^&*()_+=`{}\[\]\|\\:;'<>,.\/\? ])+/g, '-').toLowerCase().trim();
                   link = "#" + anchorTitle;
                   //Set all headers to a 0-nesting level.
                   header = 'header-nesting-0';
                   //Adjust header-nesting layers so that they point to the correct html tag. header-nesting-1 should match the second .hg-article-body h# listed above; header-nesting-2 should match the third, etc.
                   if($(this).is('h3')){
                       header = 'header-nesting-1';
                   }else if($(this).is('h4')){
                       header = 'header-nesting-2'
                   }
                   el.html('<a id="'+anchorTitle+'" class="toc-anchor"></a>' + el.html());
                   newLine =
         "<li class='"+header+"'>" +
           "<a class='article-anchor' href='" + link + "'>" +
             title +
           "</a>" +
         "</li>";
   
   
                   ToC += newLine;
                 }
                 });
        ToC +=
      "</ul>" +
     "</nav>";
       $("#snippet-prepend").before(ToC);   
   });
   
   </script>
   
   <style>
   /* CSS to style the TOC as it displays and the auto-created anchors
   .toc-top styles the box for the TOC; adjust styles here to tweak look and feel */
     
   .toc-top {
       background-color: #f5f5f5; /* set to #fff or delete entirely for no background */
       border: 1px solid #e3e3e3; /* adjust the color hex here to change border color */
       border-radius: 4px;
       box-shadow: 0 1px 1px rgba(0, 0, 0, 0.05) inset;
       margin-bottom: 20px;
       min-height: 20px;
       padding: 5px 30px;
   }
   
   
   .toc-anchor {
     display: block;
     height: 140px; 
     margin-top: -140px; 
     visibility: hidden;
   }
   
   /* Set the indentation for the nesting levels. May need to be edited to match changes above. Increase or decrease the margin-left to get your desired level of indentation. */
   .header-nesting-1 {
       margin-left: 20px;
   }
   .header-nesting-2 {
       margin-left: 40px;
   }
   </style>

   Your final snippet should look something like this when you click Save Changes:Sample nested Article TOC snippet
6. Click Save.
7. Copy and paste the merge code for your snippet into any article where you want the table of contents to appear, as shown in the Editor screenshot at the top of this article.

Customize the headings used

You can add additional heading levels beyond the example, remove unneeded headings, or begin them at a different level. Here is an example of how to begin them at a different level:

1. Customize the script to build the table of contents using different heading levels. This involves edits in a few places. First, edit the list in row 8. Here we begin with heading 3 and add heading 4 and 5:

   $(".hg-article-body h3, .hg-article-body h4, .hg-article-body h5").each(function() {

2. Next, adjust the header if statement so that it references the nesting-layers we changed above (nesting layer 1 is now h4 and layer 2 is now h5):

   //Adjust header-nesting layers so that they point to the correct html <h> tag.
                   if($(this).is('h4')){
                       header = 'header-nesting-1';
                   }else if($(this).is('h5')){
                       header = 'header-nesting-2'

Customize the Table of Contents header/wording

• Customize the Table of Contents header text. Replace "In this article:" with wording of your choice in row 5:

  "<nav role='navigation' class='table-of-contents toc-top'><h4>Quick Links</h4>" + "<ul>";

• Change the "In this article" text from an h4 to a div, p, or any other HTML element in row 5. Or remove it. Here, we've changed it to paragraph:

  "<nav role='navigation' class='table-of-contents toc-top'><p>In this article:</p>" + "<ul>";