Homepage look and feel

Homepage Overview

Your knowledge base's homepage is the initial landing page that readers will see if they go to your default link. Usually, the homepage includes things like customer support contact information, announcements, or a description of what the knowledge base contains. You can also show a list of newest and most popular articles!

Why does my home page look different in the editor than it does live?

The WYSIWYG editor, much like when you are actually editing an article, will not pull in all of your styles as it is meant to assist in text formatting. We recommend saving and previewing your progress often by clicking on the homepage URL to make sure things are looking as they should be.

Can I style my home page separately from everything else?

Yes you can. You can use the CSS merge code for the Homepage class to target styles on only that page: .hg-home-page

How do I make changes to my homepage?

There are two places you can edit your homepage:

  1. The homepage template (Knowledge Base > Home Page)
    Sample homepage template
  2. The Custom HTML for the home page (Settings > Style, Custom HTML > Home Page)
    Sample homepage Custom HTML

In general, if you like the default layout with the category tiles and the widgets, but you just want to make a couple changes to it (such as removing one of the widgets or replacing it with some text of your own, etc.), edit the template directly. If you have a very specific design you're going for, remove everything from the template and edit the Custom HTML directly.

The template mergecode *must* be referenced in the Custom HTML for the Home Page, but for complete control over your homepage, you can save the template with nothing in it and code the entire homepage in HTML.

Change the background image on my homepage

The default knowledge base theme has a grey tweed background but it's easy enough to change! You can either replace it with a banner image or with colors.

Replace with colors

Go to Settings > Style and paste the below code in the Custom CSS field. 

.ko-homepage-top {
    background-color: #8bc34a; /* Adjust to use color of your choice */
    background-image: none;
}

Replace the background-color with a color of your choice.

Pro Tip: For a little extra pizzazz, consider using a color gradient:

.ko-homepage-top {
      background-image: linear-gradient(-90deg, red, yellow);
}

Replace with your own image

Go to Settings > Style and paste the below code in the Custom CSS field. 

.ko-homepage-top {
    background-image: url(/css/images/tweed.png);
}

Next, find a suitable image. This is the trickiest part. Here are some simple tips to help you find a good image.

  1. The image should have fairly large dimensions about 1500px x 300px (this are not strict dimensions as larger images can be adjusted in this space).
  2. The image file size should be relatively small. Ideally the image file size is in kilobites (KB) not megabites (MB) as large files will slow down your website.
  3. (Alternative) You might also choose a smaller image that would look nice as tiles in the background.

Once you've selected an image upload it to your KnowledgeOwl File Library and obtain the URL to your uploaded image

Once you've obtained your image URL go back to Settings > Style > Custom CSS replace the highlighted portion below with URL to your image. 

.ko-homepage-top {
    background-image: url(/css/images/tweed.png);
}

Before you save, remove the https: from the front of your URL. This will ensure that your images loads regardless of whether your site is secure or not.

.ko-homepage-top {
    background-image: url(//dyzz9obi78pm5.cloudfront.net/app/image/id/598f28df6e121c4f36ac0cdf/n/open-book-on-orange-low.jpg);
}

Is your image repeating?

If your image is smaller than the space provided it will repeat itself. 

To fix this, you have two options:

  1. Add background-size: cover to your CSS. This will stretch the image to make it fit the overall dimensions--but sometimes this will somewhat distort or cut off parts of the image, so take a good look at the results. Your resulting CSS should look like so:
    .ko-homepage-top {
        background-image: url(/css/images/tweed.png);
    	background-size: cover;
    }
  2. If you don't like the look of background-size: cover, try adding background-size: 100% 100% to your CSS. This will try to stretch the image proportionately to fit the screen it's displayed on, which can be more elegant for lots of different devices and sometimes bypasses the off-center distortion of background-size: cover. Your resulting CSS should look like so:
    .ko-homepage-top {
        background-image: url(/css/images/tweed.png);
    	background-size: 100% 100%;
    }

Remove the homepage title

By default, the title of your knowledge base will display above the search bar of your homepage.

Sometimes, your homepage banner image may already contain your company logo or knowledge base name. In these cases, you may want to remove the default homepage title completely.

To remove the homepage title, you need to delete one line of HTML from the Home Page styles.

  1. Go to Settings > Style > Custom HTML > Home Page.
  2. Delete the line that says "<h1 class="hg-article-title" >[homepage("title")]</h1>".
    Sample homepage Custom HTML with title line circled
  3. Click Save.
    Your custom HTML should now look something like this, and your title should be gone:
    Same code example, title removed

Change the color of the homepage title

By default, the color of the Homepage title is set to white as shown below:

To change it, to black for example, go to Settings > Style and paste the below code at the bottom of the Custom CSS field:

.ko-homepage-top .hg-article-title{
    color: #000000;
}

Replace the "#000000" part with the hex code of the color of your choice.

Article Widgets

KnowledgeOwl offers four article widgets that you can use in your knowledge base to help readers find new, updated, popular, and relevant content.

Popular Articles Widget

Our Popular Articles Widget allows you to display articles with the most traffic. This will increase your readers' engagement and the your ability to get them the most common answers they might need. Your home page is an excellent place to add this widget. Check out our documentation on the Popular Articles Widget to learn more. 

New Articles Widget

Our New Articles widget allows you to display articles that have the newest information. Your home page is a great spot to place this widget to help supply readers with the most up to date information! Check out our documentation on the New Articles Widget to learn more.

Updated Articles Widget

Our Updated Articles widget allows you to display articles that have recently updated content. This will increase your readers' engagement and your ability to get them the most up-to-date answers they need. Your home page is an excellent place to add this widget. Check out our documentation on the Updated Articles Widget to learn more. 

Related Articles Widget

Our Related Articles widget allows you to display articles that have content related to the current article the reader is reading. This will increase your readers' engagement and the your ability to get them the answers they need. Check out our documentation on the Related Articles Widget to learn more. 


New Articles Widget

Our New Articles widget allows you to display articles that have the newest information. Your home page is a great place to put this widget to help readers keep up with the latest information!

How does it work?

KnowledgeOwl will search behind the scenes for the newest articles. New articles are distinguished by the last 5 published articles created.

Setup

Setting this up is easy! The below merge code is almost all you need.

 [template("new-articles")]

Add the New Articles Widget to all articles

You can place the new articles merge code in the HTML of all articles. Go to Settings > Style > Custom HTML and select Article. You can place the merge code after the article body merge code or in the hg-article-footer div.


Either of these locations will display at the bottom of each article.

You'll probably also want to add a header to display above the new article links as well and perhaps a div with a class so that you can style the new articles widget.

Something like the following should do:

<div class="new-articles">
 <h3>New Articles</h3>
 [template("new-articles")]
 </div>

Add the New Articles Widget to individual articles

If you only want to display the new articles widget in certain articles you can place the new article merge code at the bottom of individual articles. To do so, edit the article and click the Source button in the top right of the editor toolbar.

Scroll to the bottom of the article and paste the merge code.

You'll probably also want to add a header to display above the new article links as well and perhaps a div with a class so that you can style the new articles widget.

Something like the following should do:

<div class="new-articles">
 <h3>New Articles</h3>
 [template("new-articles")]
 </div>
[template("new-articles")]

Add the New Articles Widget to the right column of your Knowledge Base

Finally, you might decide to display the New Articles Widget in the right column of your knowledge base. This column was designed for this kind of content!

To do so go to Settings > Style > Custom HTML and select Right Column and paste the merge code.

You'll probably also want to add a header to display above the new article links as well and perhaps a div with a class so that you can style the new articles widget.

Something like the following should do:

<div class="new-articles">
 <h3>New Articles</h3>
 [template("new-articles")]
 </div>

Updated Articles Widget

Our Recently Updated Articles widget allows you to display articles that have recently updated content. This will increase your readers' engagement and the your ability to get them the most updated answers they need. Your home page is an excellent place to add this widget.

How does it work?

It's as simple as placing a merge code where you would like this information to be displayed! KnowledgeOwl will search behind the scenes for the most updated articles. Updated articles are determined by the Last Modified on date at the bottom of each article. 

Setup

Setting this up is easy! The below merge code is almost all you need.

[template("up-articles")]

Add the Recently Updated Articles Widget to all articles

You can place the updated articles merge code in the HTML of all articles. Go to Settings > Style > Custom HTML and select Article. You can place the merge code after the article body merge code or in the hg-article-footer div.


Either of these locations will display at the bottom of each article.

You'll probably also want to add a header to display above the updated article links as well and perhaps a div with a class so that you can style the updated articles widget.

Something like the following should do:

<div class="updated-articles">
 <h3>Updated Articles</h3>
 [template("up-articles")]
 </div>

Add the Recently Updated Articles Widget to individual articles

If you only want to display the updated articles widget in certain articles you can place the updated article merge code at the bottom of individual articles. To do so, edit the article and click the Source button in the top right of the editor toolbar.

Scroll to the bottom of the article and paste the merge code.

You'll probably also want to add a header to display above the updated article links as well and perhaps a div with a class so that you can style the updated articles widget.

Something like the following should do:

<div class="up-articles">
 <h3>Updated Articles</h3>
 [template("up-articles")]
 </div>

Add the Recently Updated Articles Widget to the right column of your Knowledge Base

Finally, you might decide to display the Updated Articles Widget in the right column of your knowledge base. This column was designed for this kind of content!

To do so go to Settings > Style > Custom HTML and select Right Column and paste the merge code.

You'll probably also want to add a header to display above the updated article links as well and perhaps a div with a class so that you can style the updated articles widget.

Something like the following should do:

<div class="updated-articles">
 <h3>Updated Articles</h3>
 [template("up-articles")]
 </div>

Popular Articles Widget

Our Popular Articles Widget allows you to display articles with the most views. This will increase your readers' engagement and your ability to get them the most common answers they might need. Your home page is an excellent place to add this widget.

How does it work?

It's as simple as placing a merge code where you would like this information to be displayed! KnowledgeOwl will search behind the scenes for the most popular articles. Popular articles are determined by the amount of traffic the articles receive. You will be able to find what articles will pop up by going to Reporting and then scrolling to the popular articles section. 


Setup

Setting this up is easy! The below merge code is almost all you need.

[template("pop-articles")]

Add the Popular Articles Widget to all articles

You can place the popular articles merge code in the HTML of all articles. Go to Settings > Style > Custom HTML and select Article. You can place the merge code after the article body merge code or in the hg-article-footer div.


Either of these locations will display at the bottom of each article.

You'll probably also want to add a header to display above the popular article links as well and perhaps a div with a class so that you can style the popular articles widget.

Something like the following should do:

<div class="pop-articles">
 <h3>Popular Articles</h3>
 [template("pop-articles")]
 </div>

Add the Popular Articles Widget to individual articles

If you only want to display the popular articles widget in certain articles you can place the popular article merge code at the bottom of individual articles. To do so, edit the article and click the Source button in the top right of the editor toolbar.

Scroll to the bottom of the article and paste the merge code.

You'll probably also want to add a header to display above the popular article links as well and perhaps a div with a class so that you can style the popular articles widget.

Something like the following should do:

<div class="pop-articles">
 <h3>Popular Articles</h3>
 [template("pop-articles")]
 </div>

Add the Popular Articles Widget to the right column of your Knowledge Base

Finally, you might decide to display the Popular Articles Widget in the right column of your knowledge base. This column was designed for this kind of content!

To do so go to Settings > Style > Custom HTML and select Right Column and paste the merge code.

You'll probably also want to add a header to display above the popular article links as well and perhaps a div with a class so that you can style the popular articles widget.

Something like the following should do:

<div class="pop-articles">
 <h3>Popular Articles</h3>
 [template("pop-articles")]
 </div>

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!