If you've noticed that your Zendesk Guide help center displays the current article at the top of the related articles list, you're not alone. This quirky behavior has puzzled many Zendesk admins, and while it might seem like a minor annoyance, it creates a confusing user experience. After all, why would someone need to click on the article they're already reading?
The good news? There's a straightforward fix that requires just a small code tweak in your help center theme.
Understanding the Problem
When users browse your knowledge base, Zendesk Guide displays a list of related articles at the bottom of each article page. This feature is designed to help users discover relevant content based on their current reading.
However, there's a well-known quirk: the article users are currently viewing often appears at the top of this related articles list.
As one Zendesk community member put it:
"Ah yeah, this is a classic and super annoying Zendesk behavior. It happens because the current article is often the most 'relevant' to itself based on its own labels."
This happens because of how Zendesk's related articles algorithm works. According to Zendesk's official documentation, the related articles list is populated based on a relevancy score system that tracks user behavior:
- A log of recently viewed articles is maintained for each user
- When someone views an article, a relationship is created between it and the previously viewed article
- Over time, articles accumulate relationships with other articles, building relevancy scores
- The more frequently articles are viewed together, the higher their relevancy score
The issue? An article naturally becomes highly "relevant" to itself based on these labels and relationships, causing it to appear in its own related articles list.
The Solution: A Simple Theme Code Fix
The fix involves adding a conditional statement to your help center theme that tells Zendesk to skip the current article when displaying the related articles list. While this isn't officially documented in Zendesk's help center, it's a solution that experienced Zendesk users have discovered and validated.
Here's how to implement it:
Step 1: Access Your Theme Editor
- Navigate to Guide Admin in your Zendesk instance
- Click on Customize design in the sidebar
- Find your active theme and click Customize
- Click Edit code to access the theme editor
Step 2: Locate the Article Page Template
In the templates folder on the left sidebar, find and click on article_page.hbs. This is the template that controls how individual article pages are displayed.
Step 3: Find the Related Articles Code Block
Look for the code block that starts with {{#each related_articles}}. This is where the related articles are rendered on the page. The code typically looks something like this:
handlebars
{{#each related_articles}}
<li>
<a href="{{url}}">{{title}}</a>
</li>
{{/each}}
Step 4: Add the Unless Conditional
Now, wrap the article link display inside an {{#unless}} helper that checks if the related article's ID matches the current article's ID. Here's what the updated code should look like:
handlebars
{{#each related_articles}}
{{#unless (is id ../article.id)}}
<li>
<a href="{{url}}">{{title}}</a>
</li>
{{/unless}}
{{/each}}
What this code does:
{{#each related_articles}}loops through all related articles{{#unless (is id ../article.id)}}checks if the current related article's ID is the same as the page's article ID- If they match (meaning it's the same article), it skips rendering that item
../article.iduses the../notation to access the parent context (the current article being viewed)
Step 5: Save and Publish
Once you've made the change:
- Click Save in the code editor
- Click Publish to make your changes live
- Test it by visiting an article on your help center and checking the related articles section
Why This Works
The magic happens with the {{#unless (is id ../article.id)}} conditional statement. This uses Zendesk's Curlybars templating language (which is based on Handlebars) to:
- Compare the ID of each related article in the loop
- Check if it matches the ID of the current article being displayed
- Skip rendering that article if there's a match
The ../ notation is crucial here because it tells the template to look at the parent context (the current article) rather than the item in the loop.
Important Considerations
Theme Compatibility: This solution works with most Zendesk Guide themes, including Copenhagen (the default theme) and custom themes, as long as they use the standard {{#each related_articles}} loop structure.
No Official Documentation: While this solution is widely used and validated by the Zendesk community, it's worth noting that it's not something officially documented in Zendesk's help center. However, it uses standard Curlybars templating helpers that are fully supported.
Testing: After implementing this change, test it thoroughly across different articles in your help center to ensure it works as expected and doesn't break any existing functionality.
Alternative Approaches
If you want more control over your related articles, you might also consider:
Label-Based Related Articles: Some Zendesk admins create custom solutions using article labels to manually control which articles appear as related content. This gives you more control but requires more maintenance.
Custom Scripts: For more advanced use cases, you can use JavaScript to manipulate the related articles list dynamically, though this approach is more complex and may impact page load times.
Wrapping Up
This simple theme modification solves a common frustration for Zendesk Guide users. By adding just a few lines of code, you can ensure that your related articles list only shows truly relevant content – not the article your users are already reading.
Remember, good user experience is all about removing friction and confusion. Small improvements like this can make your knowledge base feel more polished and professional, helping your users find the information they need more efficiently.
Have you implemented this fix? Found any other clever solutions to Zendesk Guide quirks? Share your experiences with your team and help make everyone's help center better.
About Macha AI
Macha AI builds purpose-built AI apps for Zendesk — including Copilot, Auto Reply, and Translations — designed to help agents work faster and smarter. And this is just the beginning. Many more apps are on the way. Learn more → getmacha.com
