Featured articles

Display a list of featured articles from your help center that have one or more labels.

Promoted articles are a great way to present important articles in your help center. Featured articles can be used in a similar way but are more flexible because you can filter the list of articles not only based on whether or not they’re promoted, but by other properties like labels.

The example below demonstrates the use of a custom article template showing articles with one or more specific labels.

Featured articles by label
View code
<div
  data-element="navigation"
  data-properties='[
    "id",
    "name",
    "title",
    "body",
    "html_url",
    "position",
    "promoted",
    "draft",
    "section_id",
    "category_id",
    "created_at",
    "label_names"
  ]'
  data-template="featured-articles"
  data-template-data='{ "heading": "Featured articles", "labels": [ "a_label" ], "excerptLength": 120 }'>
</div>

<template id="tmpl-featured-articles">
  <% var featuredArticles = articles.filter(function(article) {
    return article['label_names'].some(function(label) {
      return labels.includes(label);
    })
  }) %>
  <% if (featuredArticles.length) { %>
    <% if (heading) { %>
      <h2 class="h1 flex align-items-center justify-content-center mb-6">
        <%= heading %>
      </h2>
    <% } %>
    <ul class="list-unstyled row my-6">
      <% featuredArticles.forEach(function(article) { %>
        <li class="col-12 mb-4 md:col-6 lg:col-4">
          <div class="media align-items-start">
            <svg class="text-primary fill-current mr-3 mt-1" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
              <g stroke="none" stroke-width="1" fill-rule="evenodd">
                <rect opacity="0" x="0" y="0" width="24" height="24"></rect>
                <circle opacity="0.3" cx="12" cy="12" r="10"></circle>
                <path d="M12.4208204,17.1583592 L15.4572949,11.0854102 C15.6425368,10.7149263 15.4923686,10.2644215 15.1218847,10.0791796 C15.0177431,10.0271088 14.9029083,10 14.7864745,10 L12,10 L12,7.17705098 C12,6.76283742 11.6642136,6.42705098 11.25,6.42705098 C10.965921,6.42705098 10.7062236,6.58755277 10.5791796,6.84164079 L7.5427051,12.9145898 C7.35746316,13.2850737 7.50763142,13.7355785 7.87811529,13.9208204 C7.98225687,13.9728912 8.09709167,14 8.21352549,14 L11,14 L11,16.822949 C11,17.2371626 11.3357864,17.572949 11.75,17.572949 C12.034079,17.572949 12.2937764,17.4124472 12.4208204,17.1583592 Z"></path>
              </g>
            </svg>
            <div class="media-body">
              <h3 class="mt-0 mb-3">
                <a class="link-stretched text-inherit hover:text-primary" href="<%= article.html_url %>">
                  <%= article.title %>
                </a>
              </h3>
              <p class="text-gray-600">
                <%= Util.getExcerpt(article.body || '', excerptLength) %>
              </p>
            </div>
          </div>
        </li>
      <% }) %>
    </ul>
  <% } %>
</template>

The articles can be filtered and sorted in any way you like, for example by created or updated date or on the basis of how many votes they’ve received.

By making updates to the micro-template you can change the look-and-feel of the list or add new functionality. For different article list styles that you can use with this extension, check out our article list patterns.

The featured article list is displayed using our built-in Navigation extension. You can use the options described on that extension’s page to make additional design or functional changes, regardless of whether you create the article list using attributes or JavaScript.

The example provided uses the data-element="navigation" attribute to create a list of featured articles.

<div data-element="navigation" data-template="featured-articles" data-properties="..." data-template-data="..."></div>

To make design or functional changes you can either edit the default micro-template or replace it with one from our Pattern Library, updating the template ID if necessary.

If data attributes are used within article content you will need to ensure that the allow unsafe HTML setting is enabled within the Zendesk Guide settings.

You can create the list of featured articles using JavaScript:

<div id="featured-articles"></div>

<template id="tmpl-featured-articles">
  ...
</template>

<script type="text/javascript">
  ready(function() {
    new Navigation(document.getElementById('featured-articles'), {
      properties: [
        "id",
        "name",
        "title",
        "body",
        "html_url",
        "position",
        "promoted",
        "draft",
        "section_id",
        "category_id",
        "created_at",
        "label_names"
      ],
      template: "featured-articles",
      templateData: {
        heading: "Featured articles",
        labels: [ "a_label" ],
        excerptLength: 120
      }
      // Additional options go here
    });
  });
</script>

The example above supplies the same option values to the plugin as the data-attribute example. This may be desirable if you need to fetch additional data to pass through as templateData before rendering the list.

Related extensions

Animations and transitions Free

Animations and transitions

Add engaging animation and transition effects to elements.

Article navigation Free

Article navigation

Display links to next and previous articles.

Carousels Free

Carousels

Present content in well defined and easy to follow steps.