In response to a problem highlighted by Zendesk customers in this community post, we've crafted a tutorial that offers a solution for support teams wanting to automatically showcase related articles in Zendesk Guide using labels. Instead of manually adding and updating related articles, we will utilize article labels to fetch and display them dynamically.
Before we dive in, a brief note: this tutorial requires some coding. If you're new to this, don't worry. I'll explain each step thoroughly.
Overview
The idea is simple: label your articles appropriately, and when a visitor reads an article, a small script will automatically populate a list of related articles using those labels.
How it will work
1. Article Labeling: First, you need to decide on groups of articles that should be referenced together. Every article in a group gets the same label. E.g., for a group of articles about security best practices, label all of them with "security".
2. Trigger Labeling: In any article where you want to show the above group, add a special trigger label, e.g., "link_security". The script will look for this trigger, find all articles labeled "security", and list them out for you.
Implementation Steps
Step 1: Add Placeholders for Related Articles
First, you'll add a placeholder in the article template where related articles will appear.
Access the Theme: Open your help center theme in Zendesk Guide.
Edit Template: Look for the article_page.hbs template. This is where individual article content is styled and arranged.
Locate the Article Content: In the template, search for the phrase "article-content". This helps you find where the article body is defined.
Insert Placeholder: Right before the article body, paste the following HTML snippet:
<div id="add-related-articles" style="margin-bottom: 50px; display: none">
<h4>Related articles</h4>
<ul class="related-articles">
</ul>
</div>This code creates a hidden section titled "Related articles". It will display the list when articles are found.
Step 2: Add the Script to Fetch and Display Related Articles
Now, you'll add a script that finds and lists out related articles based on labels.
Scroll to the End: At the bottom of the article_page.hbs file, find the JavaScript section. If it doesn't exist, create one with <script type='text/javascript'>.
Insert the Script: Within the <script> tag, paste the code provided below
document.addEventListener('DOMContentLoaded', function () {
// create a new DOM element: used to add a new item to the list of articles
function createNode(element) {
return document.createElement(element);
}
// append a DOM element to an existing list
function append(parent, el) {
return parent.appendChild(el);
}
function show(element) {
if (element) {
element.style.display = "block";
}
}
// find the snippet in the article's html where the related articles should be added
if ((document.getElementsByClassName('related-articles') || []).length > 0) {
const current_article_id = '{{article.id}}';
// add your zendesk subdomain here
const hc_subdomain = "d3v-support.swifteq.com";
// fetch the list of labels for the current article
const article_url = `${window.location.origin}/api/v2/help_center/articles/{{article.id}}`;
fetch(article_url)
.then((rsp) => rsp.json())
// look for the labels that start with 'link_' and build a list of labels to use when searching for related articles. We obtain these labels by removing the prefix 'link_'
.then((rsp) => {
const article_labels = rsp.article.label_names || []
const tb_labels = article_labels.filter((l) => l.startsWith("link_")).map((l) => l.replace(/^(link_)/,""));
return tb_labels;
})
// get the list of articles that have at least one of these labels
.then((tb_labels) => {
if (tb_labels.length === 0) return [];
const label_articles_url = `${window.location.origin}/api/v2/help_center/articles/search.json?per_page=100&locale={{article.locale}}&label_names=${tb_labels.join(',')}`;
return fetch(label_articles_url).then((rsp) => rsp.json()).then((rsp) => (rsp || {}).results || [])
})
// dynamically add the link to each article to the related articles list
.then((articles) => {
// only display the related articles section if we found at least one related article
if (articles.length > 0) {
show(document.getElementById('add-related-articles'));
}
const ul_tb = (document.getElementsByClassName('related-articles') || [])[0];
ul_tb.innerText = "";
return articles.filter((a) => a.id.toString() !== current_article_id).map(function(article) {
let li = createNode('li'),
span = createNode('span');
span.innerHTML = '<a href ="' + article.html_url + '">'+article.title+"</a>";
append(li, span);
append(ul_tb, li);
})
})
.catch((err) => {
console.log(err)
})
}
})
This script waits for the article to load, then checks for the trigger label. If found, it fetches articles with the corresponding group label and lists them in the "Related articles" section.
How to Test
Label Articles: Start by labeling a group of articles with a common label, e.g., "security".
Trigger the Script: In an article where you want to display the above group, add the label "link_security".
View the Article: Open the article with the "link_security" label. You should see a "Related articles" section listing articles labeled "security".
Summary
With this implementation, support teams can easily manage and display related articles without manual updates. Just remember to label your articles consistently, and the script will take care of the rest. Happy coding!