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.

Look before you leap
Consider using a topic display category with individual articles for each section, rather than these snippets. Topic display categories give you an automatic Quick Links section at the top and the option to have each article they contain within an expanding/collapsing accordion.

We have two snippets for you to use:

Single level heading snippet: Creates a table of contents using a single level of headings (set to Heading 2, but you can override it).
Multiple level heading snippet: Creates a nested table of contents using several levels of headings (Heading 2, Heading 3, and Heading 4). This article demonstrates this snippet.

For either snippet, you'll follow the same general process:

Create the snippet.
Optional: Make any customizations to the snippet to style it.
Add the snippet to either individual articles or to your Customize > Style page to add it to all articles.

Walk through the steps below.

Limitations
These snippets won't generate a table of contents in downloaded PDFs, as they depend on Javascript executing after the page loads, whereas PDFs are generated when the article is saved. They also won't work properly if added to articles that are within a topic display category.

Step 1: Create the snippet

We offer snippets like this as courtesy standalone customizations for your knowledge base. Using multiple snippets together may cause unintended consequences. Please snippet responsibly and remember that some problems are best solved by a developer!

First, let's create our snippet:

In the left navigation, select Snippets. The Snippets page opens.
Select Create New Snippet.
Enter a Snippet Name, like "Article TOC".
The snippet Merge Code Name autogenerates from that name, but you can edit it if you'd prefer a different merge code.
Enter a Snippet Description, like "Generate an automatic article table of contents from H2s" or "Generate an automatic article table of contents from H2s, H3s, and H4s".
In the right column, check the box to Hide from PDFs.
In the Snippet Content section, select the dropdown to switch from WYSIWYG Editor to Code Editor:
Gif showing the toggle to Snippet Content Code Editor. Hover to play gif.

To generate a table of contents from a single heading level, like all Heading 2s in your article, copy the code below and paste it into the Snippet Content Code Editor:

<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>

For customizing this snippet, refer to Single heading level snippet customizations.

To generate a table of contents with nested/bullet point headings for multiple layers of headings, copy the code below and paste it into the Snippet Content Code Editor:

<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;
    $(".hg-article-body h2, .hg-article-body h3, .hg-article-body h4").each(function() {
        el = $(this);
        // Remove trailing # if present (caused by ko-header-anchor)
        if(el.hasClass('ko-header-anchor')) {
            title = el.text().slice(0, -1);
        } else {
            title = el.text();
        }
        if(title !== '') {
            var anchorTitle = title.replace(/([~!@"#$%^&*()_+=`{}\[\]\|\\:;'<>,.\/\? ])+/g, '-').toLowerCase().trim();
            link = "#" + anchorTitle;
            // Determine nesting level
            header = 'header-nesting-0';
            if(el.is('h3')) {
                header = 'header-nesting-1';
            } else if(el.is('h4')) {
                header = 'header-nesting-2';
            }
            // Add anchor if it doesn't already exist
            if (!el.hasClass('ko-header-anchor')) {
                el.html('<a id="'+anchorTitle+'" class="toc-anchor"></a>' + el.html());
            }
            var 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>

For customizing this snippet, refer to Multiple heading level snippet customizations.

Select Create.

With your snippet created, decide how you want to customize it before you use it.

Step 2: Customize your snippet

If you chose the single heading level snippet in step 7, refer to the Single heading level snippet customizations below.

If you chose the multiple heading level snippet in step 8, refer to the Multiple heading level snippet customizations below.

Single heading level snippet customizations

For the single heading level snippet (the code block in step 7 of the steps to create the snippet), the two most popular customizations are changing the heading level the table of contents builds from and customizing the heading text or level for the table of contents.

Once you customize your snippet, choose how you want to use it.

Build table of contents from different heading level

The script above will build your table of contents from all heading 2s in your article.

If you'd prefer to build it from another heading level instead, edit the .hg-article-body h2 in row 8. Here, we've changed it to h3 for Heading 3:

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

Change the table of contents header style or wording

To customize the header or wording for the table of contents, edit row 5.

For example, to change the "In this article:" label, edit the wording between the <h4> and </h4> tags in row 5. Here, we've changed it to "Table of contents":

var ToC = "<nav role='navigation' class='table-of-contents toc-top'><h4>Table of contents</h4><ul>";

For content hierarchy purposes, you may not want the table of contents to appear as an h4. You can change it to an h2, h3, paragraph, div, or any other HTML element by editing the <h4> and </h4> tags in row 5. Here, we've changed it to an h2:

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

Multiple heading level snippet customizations

For the multiple heading level snippet (the code block in step 8 of the steps to create the snippet), the two most popular customizations are choosing the headings to include in the table of contents and customizing the heading text or level for the table of contents.

Once you customize your snippet, choose how you want to use it.

Choose the headings to display

The script above will generate table of contents entries for all h2s, h3s, and h4s in your article.

To add or remove headings from this, make two edits:

Edit row 6 to include only the headings you care about.
Edit rows 17-23 to include the levels you care about.

To remove h4s, edit row 6 to remove the comma after the h3 and remove the h4 portion, so we'd go from this:

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

To this:

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

And we'd remove the h4 and header-nesting-2 logic from rows 21-23:

// Determine nesting level
      header = 'header-nesting-0';
      if(el.is('h3')) {
        header = 'header-nesting-1';
      }

Change the table of contents header style or wording

To customize the header or wording for the table of contents, edit row 4.

For example, to change the "In this article:" label, edit the wording between the <h4> and </h4> tags in row 4. Here, we've changed it to "Table of contents":

var ToC = "<nav role='navigation' class='table-of-contents toc-top'><h4>Table of contents</h4><ul>";

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

Step 3: Use your snippet

You can choose whether you want to use your snippet only in select articles or add it to all articles in your knowledge base. Refer to the more detailed instructions below for each approach.

Use snippet in specific articles

To add the table of contents only to specific articles:

Open the article for editing.
Put your cursor in the editor pane where you want the table of contents to appear.
Select the editor's Insert Snippet control and search for the snippet.
Select it and insert it.

The snippet displays in the editor where you inserted it. In the live article, that snippet is replaced with the table of contents.

Refer to Add snippets in content for more detailed instructions on adding snippets to articles.

Use snippet in all articles

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

Go to Customize > Style (HTML & CSS).
In the Customize HTML, CSS, and JS section, select Custom HTML.
Select Article from the Select HTML section to edit dropdown.

Add the snippet mergecode in where you'd like it to appear. For example, adding it on row 11 of our example, as the first line of the hg-article-body, will place it after the article's title and metadata, but before the article body:

<div class="hg-article">
    <div class="hg-article-header">
        <h1 class="hg-article-title">[article("title")][article("action_icons")]</h1>
        <div class="metadata">
            [article("required_reading_flag")]
            [translation("article:last-modified-on-label")] 
            [article("date_modified")]
        </div>
    </div>
    <div class="hg-article-body">
    
        [article("body")]
        [article("required_reading_acknowledgement")]
    </div>
    <div class="hg-article-footer clear-both">
        <div class="ko-related-articles text-center">
            <h3>[translation("article:related-articles-heading")]</h3>
            
						
						Topic display: Change Quick Links style and/or add header						
					
									
						Change the icons used in the table of contents						
					
									
						Widget Customize Text section						
					
									
						Add anchors within articles						
					
									
						Color picker: Which colors control which parts of my theme?						
					
				
        </div>
        	
	
	
	
	
	
		Was this article helpful?	
	
					
				
			
			
				
			
			


	Thank you for your feedback!

        
	
	
	
		
            Knowledge 1
        
            Knowledge 2
        
            Knowledge From
        
         

	
		
			
											
									
			
				
			
			
		
		
							
					
						Name
						
					
					
						Email
						
					
				
				
										
					Comment!
					
				
					
		
	
	
		
			Thanks! Your comment will appear when it's approved :)
		
	
	
	


	
			


    </div>
</div>

Be sure to Save your changes.

Create an article table of contents (TOC) from headers

Step 1: Create the snippet

Step 2: Customize your snippet

Single heading level snippet customizations

Build table of contents from different heading level

Change the table of contents header style or wording

Multiple heading level snippet customizations

Choose the headings to display

Change the table of contents header style or wording

Step 3: Use your snippet

Use snippet in specific articles

Use snippet in all articles

Related Articles