Create a custom homepage articles list

By default, your knowledge base comes with three article lists on the homepage:

• Popular Articles list
• New Articles list
• Updated Articles list

You can also add a Recent Articles list to your homepage. But what if you'd like to build your own list?

Learn how to build a homepage articles list that populates with articles assigned a specific tag, using an API Snippet. It can be useful for setting up Frequently Referenced articles, Quick Links, and so on.

Step 1: Create your tag and add it to articles

In order to have a list that pulls all articles with a particular tag, the tag needs to exist and needs to be assigned to articles.

You can create a tag any time on the fly by opening an article in edit mode and typing into the Tags section. Once you save, the tag is created and assigned to the article.

You can see all tags in your knowledge base by going to Library > Tags.

Step 2: Get your tag's ID

Once your tag has been created, you'll need to know its tag ID, which is a unique identifier for that tag. We use the ID here in case the tag is ever edited--the ID won't change even if the spelling of the tag does.

There are few ways to get your tag's ID. The fastest way is to go the Tags Library and inspect the tag. We offer instructions on how to do that below. (If you have an API key and you're comfortable using it, you can make an API call to the tag endpoint to get it.)

Getting the tag ID from the Tags Library

To get the tag ID from the Tags Library, we'll use your browser's built-in Inspect option to look at the code in the page.

1. Go to Library > Tags.
2. Right-click on the tag whose ID you want to get and select Inspect.
3. This will open some element details for the tag in a different pane. Look two rows up from the tag-pill with the text of the tag you selected. The value listed there is the tag ID:
   
   Sample tag ID in dev tools
   
4. Copy and paste this tag ID somewhere for later.

Step 3: Create a snippet that looks up articles for your tag

Now the real fun begins. We'll create an API snippet that will pull the list of articles that have that tag assigned, so it can be displayed in a list on the homepage:

1. Go to Library > Snippets.
2. Select the + Create New Snippet button.
3. Give your snippet a name. In this example, since I'm using the tipsandtricks tag, I'll call it tipsandtricks Articles.
4. The Merge Code Name will be automatically generated from the snippet name. You can edit it if you'd like.
5. Add a description so you remember what this snippet does.
6. Select the Snippet Content editor, which should say WYSIWYG Editor, and select Code Editor instead.
   
   Select Code Editor from the Snippet Content dropdown
   
7. Once in Code Editor, copy and paste the code below into the editor:

   <ul class="list-unstyled stat-list" id="<name>">
   </ul>
   
   
   <script>
   $(function(){
       //get all articles inside 
       $.get('[ko_api(article|{"project_id": "%cur_kb_id%", "tags": {"$in":["<tag-id>"]},"status": {"$in": ["published", "review"]}, "_fields": ["url_hash","name"],"sort": {"name": 1}})]',
           function(data) {
               if(data && data.data && data.data.length > 0) {
                     $.each(data.data, function(index, article){
                       $("#<name>").append('<li><div><a href="/help/'+article.url_hash+'">'+article.name+'</a></div></li>')
                   });
               }
             }).fail(function(error) {
             //failed
       });      
   });
   </script>

8. In row 1, replace <name> with a label or name that makes sense for your list. Be sure you keep the quotes around it. So if I'm creating this for my tips and tricks, I might use id="tips".
9. Use that same name in row 12, where it says $("#<name>"). Be sure to keep the quotes and the # in front of it. So if I used id="tips" for the first one, I'll use $("#tips") here.
10. In row 8, replace <tag-id> with the tag ID you copied in Step 3. Keep it in "quotes".
11. In row 12, if your knowledge base URL ends in something other than /help (such as /docs or /home), update the <a href="/help/' portion to have the correct location. Replace "/help' with "/home' or "/docs' as appropriate.
12. Here is what my complete snippet looks like for my tipsandtricks tag. In my case, the knowledge base I'm in was using /docs, so I updated row 12 to reflect that change:
    
    Sample completed snippet that uses the id "tips" and the /docs/ URL instead of /help/
    
13. Optional: if you'd like this list to only be displayed to certain groups, use the Restrict to Reader Groups checkboxes in the right panel to choose the groups to show it to.
14. Once you've finished making changes, select the Create button to create and save your snippet.

Step 4: Test your snippet

To test that your snippet is working:

1. Create a new article.
2. Add the snippet to your article.
3. Publish the article and view it. If your snippet is working, you'll see a list of the articles with the tag you used. If it's not working, be sure you have at least one API key, and be sure that the a href path matches your knowledge base. Reach out to our support team if you're having issues.

Step 5: Add your snippet to your homepage

Now that all the architecture is built for the list, let's add it to the homepage. How to do this depends on where you'd like to add the list:

• If you'd like to add the list in with your existing article lists, or replace one of those article lists, follow the instructions to Update the Homepage Custom HTML.
• If you'd like to add the list below the categories on the homepage but above all the other lists, follow the instructions to Update the Homepage content.
• If you're using an older theme with a Right Column and you'd like to add the list there, follow the instructions to Update the right column.

Update the Homepage Custom HTML

If your knowledge base is not using the [homepage("body")] template, you can add the snippet merge code for your API snippet directly into the Custom HTML. You'll need to reference the snippet's Merge Code Value:

1. Go to Library > Snippets.
2. Open the snippet you created for this list.
3. Copy the snippet's Merge Code Value.
   
4. Go to Style > Settings.
5. Be sure Custom HTML is selected.
6. Select Homepage from the Custom HTML dropdown.
7. Paste the merge code into an appropriate div, paragraph, or whatever you'd like here. If in doubt, you can copy the HTML for one of the other lists, swap out the titles, and replace the article list's template merge code with the snippet merge code.

Update the Homepage content

If you want to place this list in your homepage's body content within the [homepage("body")] template, rather than editing the Custom HTML directly, it is easier to edit the homepage content itself. To do so:

1. Select Homepage from the lefthand navigation.
2. Create a heading for the section, like "Tips & Tricks".
3. Use the Insert Snippet option to insert your snippet merge code beneath the heading.
   
   Use the Insert Snippet option
   
4. You can Preview the changes if you'd like, but be sure you click Save to save them!

Update the right column

If you want to add the new list into your Homepage Right column:

1. Go to Library > Snippets.
2. Click on the snippet you created for this list.
3. Copy the snippet's Merge Code Value and paste it somewhere where you can find it.
   
4. Go to Settings > Style.
5. Select Custom HTML > Right Column.
6. Wherever you'd like to add the list, copy the code below and paste it into that HTML:

   <div class="panel panel-default right-col-panel <custom-panel>">
     <div class="panel-heading"><list-title></div>
     <snippet-merge-code>
   </div>

7. In row 1, replace <custom-panel> with a label for this panel that makes sense (I used "tip-panel"). Be sure that you leave the closing quotation mark.
8. In row 2, replace <list-title> with the title you'd like displayed (I used Tips & Tricks).
9. In row 3, replace the <snippet-merge-code> with the merge code you copied in Step 3.
10. So if I adjust this for my Tips & Tricks setup, it might look like this:

<div class="panel panel-default right-col-panel tips-panel">
  <div class="panel-heading">Tips &amp; Tricks</div>
  
</div>

11. Save your changes.

Use Cases

You can use lists like this to provide curated lists of content on your homepage that will update dynamically based on a tag being added to or removed from articles. In internal knowledge bases, these can be a great way to put frequently-referenced articles on your homepage. In software support knowledge bases, these can be a great way to highlight documentation from your latest release. We've also seen customers use these for Announcements.

You can replace all the out-of-the-box homepage article lists, or just one, or add additional lists (though you may have to play with formatting for more than 3 to look good).

Have you added a custom article list to your homepage? Share your use case with us!