Create a custom home page articles list

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

• Popular Articles List
• New Articles List
• Updated Articles List

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

This article will teach you how to build a home page 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 find 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. The value you see is the tag ID:
   
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 home page:

1. Go to Library > Snippets.
2. Select the + Create New Snippet button.
   
   Select + Create New Snippet to begin
   
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. Click the WYSIWYG Editor dropdown next to Snippet Content and select Code Editor from the dropdown.
   
   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":["YOUR-TAG-ID"]},"status":"published","_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, where it says id="NAME", 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 YOUR-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), you will also need to update the <a href="/help/' portion to have the correct location. Replace "/help' with "/home' or "/docs' as appropriate.
12. Here is what my sample code looks like for my tipsandtricks tag (I did not need to update /help/ because that's what my knowledge base uses):
    
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 home page

Now that all the architecture is built for the list, let's add it to the home page. How to do this depends on how your knowledge base has been customized already and where you'd like to add the list:

• If you'd like to add the list to the Right Column of your home page, see "Update the Home Page Right column" below.
• If you'd like to add the list to the main body of your home page:
  • Go to Settings > Style and look at the Custom HTML for the Home Page.
    • If there's very little content and you just see a reference to the [homepage("body")] template, then you'll need to follow the steps below for editing Knowledge Base > Home Page. This is the most common configuration. See "Update the Home Page Body template" below.
      Sample home page layout with homepage body template
    • If you see a lot of HTML formatting other widgets, etc., you'll want to edit Settings > Style, Custom HTML > Home Page directly. See "Update the Home Page Custom HTML" below.

Update the Home Page Right Column

If you want to add the new list into your Home Page 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.
   
   Copy the Merge Code Value
   
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.mySample}}
   </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.mySample}} with the merge code you copied in Step 3.
10. Save your changes.

Here's a sample of how I added this code into my right column:

Sample added to my right column. Note that I've given this the "tips-panel" class, added my title, and updated my snippet merge code.

Update the Home Page Body template

If you saw [homepage("body")] somewhere in your Home Page Custom HTML, you probably already have a home page that has some of our pre-built articles widgets on it. Rather than editing the Custom HTML directly, it is easier to edit the home page body template itself. To do so:

1. Go to Knowledge Base > Home Page. It will likely look something like this:
   
   Default Home Page Body Layout
2. You can either replace one of the existing article list templates or add another (if you add another, you may have to play around with formatting to get things to align well).
3. Add a title for your new articles list (default settings for article lists are Heading 3).
   
4. Place your cursor under the title. Then select the Insert Snippet control (two gear cogs icon) from the editor toolbar.
5. Type in part of the name to find the snippet, then select it and select Insert Snippet.
   
   The Insert Snippet control in the editor
   
6. You can Preview the changes if you'd like, but be sure you click Save to save them!
   

Update the Home Page 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. Click on the snippet you created for this list.
3. Copy the snippet's Merge Code Value.
   
   Copy the snippet's Merge Code Value
   
4. Go to Style > Settings. Paste the merge code into an appropriate div, paragraph, etc., in the Custom HTML for your Home Page.

Use Cases

You can use lists like this to provide curated lists of content on your home page 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 home page. 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 home page article lists, or just one, or add additional widgets (though you may have to play with formatting for more than 3 to look good).

Have you added a custom home page widget to your knowledge base? Share your use case with us!