Create a custom home page articles widget

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

This article will teach you how to build a home page articles widget 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.

Note: You must have at least one active API key in your account with ONLY GET permission to use this functionality. To retrieve / generate a KnowledgeOwl API key, have an account administrator go to to Your Account > API and create/verify that a GET-only API key exists.

Step 1: Create your tag and add it to articles

In order to have a widget 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 two ways to get your tag's ID. The fastest way is to go the Tags Library and inspect the tag. If you have an API key and you're comfortable using it, you can make a URL-based API call to 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.

Getting the tag ID with a URL-based API call

  1. Get the project_id for your knowledge base. When you are in Articles in your knowledge base, the project_id is the number that comes after the id/ portion:

  2. Copy this URL and paste it into your browser's address bar:
    https://app.knowledgeowl.com/api/head/tag.html?_authbykey=YOUR-API-KEY&project_id=YOUR-PROJECT-ID&name=YOUR-TAG-NAME
  3. Replace YOUR-API-KEY with an API Key with GET permissions.

  4. Replace YOUR-PROJECT-ID with the ID of your knowledge base you copied in Step 1. (You'll also need this later on for creating the snippet.)

  5. Replace YOUR-TAG-NAME with the text of the tag you want to use.

  6. Hit enter to run that URL.
    Running this will give you a JSON record for the tag. So, for example, here is an API call looking up a tag called "tipsandtricks":

  7. The [id] is the ID we will need later--copy it and paste it somewhere.

Pro Tip: if your tag contains spaces or punctuation, you may need to encode these so they'll be "read" properly in the URL call. Spaces should be automatically replaced with "%20" when you run the call. For encoding other types of punctuation, try something like W3School's HTML URL Encoding Reference.

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 widget on the home page:

  1. Go to Library > Snippets.
  2. Click 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. Click the WYSIWYG Editor dropdown next to Snippet Content and select Code Editor from the dropdown.
  7. Once in Code Editor, copy and paste this code into the editor:
  8. <ul class="list-unstyled stat-list" id="NAME">
    </ul>
    
    
    <script>
    $(function(){
        //get all articles inside 
        $.get('[ko_api(article|{"project_id": "YOUR-PROJECT-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>
  9. Replace id=NAME near the top, and $("#NAME") below with the same label. This name should fit the widget you'll be putting on the home page. Keep the quotes around them and keep the # in front of the second.
  10. Replace YOUR-PROJECT-ID with the knowledge base ID you used in the URL call in Step 2. Keep it in "quotes".
  11. Replace YOUR-TAG-ID with the tag ID you copied in Step 3. Keep it in "quotes".
  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.
  13. 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):
  14. Click Create to save your snippet.

Step 4: Add your snippet to your home page

Now that all the architecture is built for the widget, let's add it to the home page. How to do this depends on how your knowledge base has been customized already. So, first, go to Settings > Style and look at the Custom HTML for the Home Page.

If you 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.

Sample home page layout with homepage body template

If you do not see the homepage body template, you can edit Settings > Style, Custom HTML > Home Page directly.

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 widget 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 widget (default settings for article widgets are Heading 3).
  4. Under the title, insert the merge code for the snippet you created earlier. To do this easily, you can go to Insert Snippet, type in part of the name, and insert.
  5. 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 > Files.
  2. Click on the snippet you created for this widget.
  3. 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 widgets 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 Announcement widgets and tagging articles as announcements.

You can replace all the out-of-the-box home page article widgets, 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!