Enable & configure favorites

Favorites is designed to be used with individual reader accounts, so we recommend only enabling it if your knowledge base has an option to log in. (If you are using Public Default access, enabling it won't hurt anything--anyone who's not logged in just won't see the star to favorite an article, and any article lists you add to display favorites will show empty for them.)

Getting favorites fully set up is generally a multi-step process, in which you:

  1. Enable the feature.
  2. Adjust your Article Custom HTML to be sure it has a merge code that includes the favorites action.
  3. Figure out where you'd like to display favorites in your theme (we have a merge code you can add to your homepage or right column, depending on your theme layout, and we're exploring adding it to the table of contents but don't have a solution for that yet).

Each step is outlined in more detail below.

Enable favorites

Our default Editor role has permission to enable article ratings. If you're using a custom user role, that role must have the Admin Permission to Update article favorites settings.

To enable favorites in your knowledge base:

  1. Go to Settings > Article Favorites.
  2. Check the Enable article favorites checkbox to turn the feature on.
  3. Be sure to Save your changes.

Make sure your Article Custom HTML includes the correct merge code

Once you've turned on the feature, you also may need to make some tweaks to your article layout before you'll see the favorites star:

  1. Go to Settings > Style.
  2. Below the preview pane, be sure Custom HTML is selected.
  3. In the Custom HTML dropdown, select Article.
  4. In the Article Custom HTML, if you see the article("action_icons") template, you don't need to do anything else!
  5. If you don't see the article("action_icons") template, you probably have hard-coded HTML for your article actions, which usually looks like this:
  6. You have two options:
    1. You can highlight all of the HTML for the ko-article-actions span, remove it, and replace it with the article("action_icons") template. For more detailed instructions, see Update your article actions merge code.
    2. If you don't want to touch that HTML, you can add a new merge code into the HTML to enable the favorites icon. To do so:
      1. In the -- Select a Merge Code -- dropdown below the HTML pane, find the Article Merge Codes section.
      2. Select the Article Favorites Action from the dropdown.
      3. You can either put your cursor where you need in the HTML and hit the Insert button, or copy the merge code and paste it in.
      4. If your Article HTML looks like that in the screenshot above, you'll want to insert the merge code between the </a> and the </span>, like this:
  7. You can Preview your changes to be sure they look good.
  8. Just be sure to Save your changes once you're done!

Any one of these approaches should add a star in your article actions section as long as you enabled Favorites first:

Sample article favorites icon

Readers can click on that star to add it to their Favorites list.

Add the Favorites merge code to your home page, footer, or right column

Okay, so at this point, readers have been able to favorite things--but they don't have any way to access that list of favorites!

We've created a merge code so you can add the favorites list into your knowledge base's theme. Places you could consider adding it:

  • If your theme has had minimal customizations, most of your homepage likely lives in Knowledge Base > Home Page. You can add a section for your Favorites here.
  • If your theme has had customizations, your homepage code might live in Settings > Style, Custom HTML > Home Page. You can add a section for your Favorites here.
  • If you are using a layout that includes the Right Column, you can choose to add a section to your Settings > Style, Custom HTML > Right Column for your favorites.
  • To the footer of all articles, similar to the Related Articles section, in Settings > Style, Custom HTML in either the Body or the Article template.

Below, we'll walk through a couple of these as examples. For all options, you can control the number of favorites displayed in the list, too.

Add Favorites to Knowledge Base > Home Page

If the body of your homepage is set in Knowledge Base > Home Page, you can choose to replace one of the existing article lists with the Favorites list, or add the Favorites list on as an additional section.

Replace existing article list with Favorites

To replace an existing article list with Favorites:

  1. Go to Knowledge Base > Home Page.
  2. Find the list you'd like to replace. In this example, we'll replace the Popular Articles list. Here's what that looks like before we make any changes:
  3. Each pre-built article list has a template below it. For example, for the Popular Articles list, this is [template("pop-articles")].
  4. Copy the merge code below and paste it in to replace the existing list merge code:
    [reader("favorite-articles")]
  5. Update the heading for the article list so it makes sense (here, we use My Favorites).
  6. You can Preview your changes to be sure they look good.
  7. Be sure to Save your changes once you're done.

Add new article list section for Favorites

While this Home Page layout has a WYSIWYG editor, to add a totally new section to your home page, we recommend using the Code View option in the upper left of the editor:

  1. Go to Knowledge Base > Home Page.
  2. In the upper left of the editor, click the </> button to toggle to Code View.
  3. The existing article lists are each set up within a div with class="col-md-4 col-sm-6", which helps handle the spacing. Highlight one of the full divs and copy it:
  4. Move your cursor where you'd like the new list to live and paste that code in.
  5. Now update the text between the <h3> and </h3> tags to be the title you'd like for the list. Here, we use My Favorites.
  6. Update the [template] portion that comes after so that it reads: (you're basically replacing the word template with reader and whatever word comes before articles with favorite).
  7. Once you're done making changes, it should look a bit like this:
  8. By default, this setup will bump the fourth list onto a new row. If you'd rather shrink all your lists a little so that you can fit all 4 onto a single row on medium to large screens, you can adjust the div class for all the article lists to col-md-3 instead of col-md-4.
  9. You can Preview your changes to see what they look like.
  10. Be sure to Save once you've finished making changes!

Add Favorites to Settings > Style

If your homepage code is not in Knowledge Base > Home Page, it will be in Settings > Style. If you'd like to add your Favorites section to your Right Column, you'll also head to Settings > Style.

For homepage adjustments here, you can follow the same basic steps whether you're editing the Right Column or the Home Page, you'd just select the appropriate area in the Custom HTML dropdown.

Here, we'll walk through the Home Page:

  1. Go to Settings > Style.
  2. Below the Preview pane, be sure Custom HTML is selected.
  3. Select Home Page from the Custom HTML dropdown.
  4. In this Custom HTML, you can either edit one of your existing article lists to change it to Favorites, or add a new section. The same basic steps are followed as in the Knowledge Base > Home Page instructions above, though there is no WYSIWYG in this view (but there is a Merge Code dropdown that will help you get the merge code in!)
  5. To edit an existing article list:
    1. Locate the article list you'd like to repurpose. Here, we'll replace Popular Articles:
    2. Edit the text between the <h3> and </h3> tags to be the title you'd like for the list. We'll replace Popular Articles with My Favorites.
    3. Delete the merge code that comes after that text, beginning with the [ and ending with the ]. So you should go straight from the </h3> to the </div>:
    4. Leave your cursor between the </h3> and the </div>
    5. Click in the -- Select a Merge Code -- dropdown.
    6. In the Article List Merge Codes section, select Favorite Articles.
    7. Click the Insert button.
    8. This should insert your merge code where you had your cursor. (You can also copy and paste the merge code in there if it's easier!)
    9. You can Preview your changes; just be sure to Save them once you're done!
  6. To add to your existing article lists, copy one of the full divs for an article list and paste it where you'd like to add the Favorites. Then proceed with replacing the text and merge code as in the steps above. If you already have three article lists and you're adding a fourth, you can consider adjusting all the article lists to use col-md-3 instead of col-md-4 to get them to fit on a single row.