Handlebars Helpers for Custom Templates
If you're building a custom HTML template for your HelpDocs, you'll eventually need to use some of our helpers and partials.
Helpers
Helpers are extensions to the regular Handlebars syntax that allow you to manipulate data, loop through arrays, show HTML conditionally, and more. We've made a number of helpers to help you with common tasks.
Using Helpers
There's a few different ways to use helpers:
- Inline helpers
The simplest way to use helpers is inline. e.g.<<fallback article.title "Untitled Article">>
...will render literally to the article's title if it exists, falling back to "Untitled Article" if not. - Block helpers
Block helpers can help you do conditional statements and loops. You prefix the helper name with a hash, and write extra HTML (or even more Handlebars) inside. Then use an else block for when the condition is not true. e.g.
<<#if article.is_featured>>
This article is featured!<<else>>
Not featured, sorry :(<</if>>
...will render to "This article is featured!" if the article is featured, "Not featured, sorry :(" if not. - Combining helpers
Need to combine more than one helper? Use brackets! This is super helpful if you wanna display something conditionally, e.g.<<#if (gt category.meta.num_articles 1)>>
This category has more than one article<</if>>
...will only show "This category has more than one article" if the category does in fact have more than one article.
Bundled Helpers
Helper Name | Description | Example Usage |
if | Only show the content of the block if the condition is true, else show the content of the else block (if it exists) | <<#if article.is_featured>> |
unless | Opposite of if. Only show the content of the block if the condition is false, else show the content of the else block (if it exists) | <<#unless article.is_private>> |
each | Loop through an array. The current item is provided as this, you can access the root scope with @root, the current index with @index, and use @first and @last to see if this is the first or last item | <<#each category.articles>> |
eq | Checks if the two numbers passed are equal | <<#if (eq this.meta.num_articles 1)>> |
gt | Checks if the first number is greater than the second | <<#if (gt this.meta.num_articles 1)>> |
lt | Checks if the first number is less than the second | <<#each this.articles>> |
multiply | Multiplies two numbers together | <div class="margin-left:<<multiply @index 0.5>>em;"</div> |
divide | Divides the first number by the second | <<#unless (gt (divide @index 2) 5)>> |
add | Adds two numbers together | This is loop number <<add @index 1>> |
subtract | Subtracts the second number from the first | 2 - 1 = <<subtract 2 1>> |
hasPrefix | Checks if a string starts with a string prefix | <<#if (hasPrefix category.icon "fa-")>> |
hasSuffix | Checks if a string ends with a string suffix | Suffix ends in fix:<<hasSuffix "Suffix" "fix">> |
trimLeft | Strips prefix of string | URL without prefix: <<trimLeft "https://www.helpdocs.io/demo" "https://www.helpdocs.io">> |
trimRight | Strips suffix of string | URL without suffix: <<trimRight "https://www.helpdocs.io/demo" "/demo">> |
deepLookup | Behaves like the built-in Handlebars lookup helper, but returns an object of the original type rather than converting to a string | The first category title is <strong><<deepLookup (deepLookup category.articles 0) "title">> |
formatDate | Show a date in a format of your choice. Supported tokens: D, DD, M, MM, YY, YYYY , hh, mm, and ss. Premade formats: | <<formatDate article.updated_at "DD.MM.YYYY |
fallback | If the first value exists, returns that. If not, returns the second | <<fallback meta.home_path "/">> |
filterCategoriesByParentId | Used to find all subcategories of a given category ID | <<#each (filterCategoriesByParentId @root.meta.sidebar_categories this.category_id)>> |
categoryById | Find a category by its ID | This title of the category of this article is <<(categoryById meta.sidebar_categories article.category_id).title>> |
categoryIsAscendent | Checks if a category is ascendent of another. Useful when working with subcategories and sidebars | <<#if (categoryIsAscendent @root.meta.sidebar_categories @root.category this)>> In the example here the second parameter this is also a category. It's checking if the second category is ascendent of the first. |
i18n | Find the current language version of a given internationalization key, falling back to the second string | <a onclick="showContactForm();"> |
page | Only display the contents of a block if the page is equal to the given page. Possible values: home (can also be called categories), category, article, search | <<#page "home">> |
isPermissioned | Shows content of a block if the article has any permissions on it. Requires article to be passed through | <<#isPermissioned article>> |
Partials
Partials in Handlebars are snippets of HTML we provide for your convenience. Just like the partials you write yourself for the header and footer, these let you use reusable code that we maintain, without the effort.
Using Partials
You can use partials with the Handlebars partial syntax. For instance to create a contact button you can use <<> contactLink>>. That will render a clickable contact link your users can use to contact you.
Because we maintain it, a) you don't have to worry about it, and b) it'll respect any integrations you have set up in your account.
Bundled Partials
Partial Name | Description | Example Usage |
contactLink | Contact link that respects any connected integrations and your contact preferences in Settings. The class parameter will add a CSS class to the button of your choice, overriding the default button class applied |
|
categoryBreadcrumbs | Breadcrumbs that lead to your current page. This should be used in the category.hbs and article.hbs content partials only. The linkify parameter indicates whether the last category in the list should be wrapped in a hyperlink (like for an article page) or not (like for a category page) |
|
hdFooter | Renders the HelpDocs footer according to your preferences in Settings > Brand. We require this to be present on all accounts, but you can include it anywhere you like |
|
Custom Partials
We support the Handlebars 4 inline partial syntax, so you can make your own partials. This is super handy if you need to do anything recursive (like nesting categories) or repetitive (so you don't have to maintain two lots of the same code).
You can create a custom partial like this:
<<#*inline "myArticle">>
<h3><<article.title>><h3>
<p><<article.description>></p>
<</inline>>
Then invoke it just like you'd invoke any other partial, passing parameters if you like:
<<#each category.articles>>
<<> myArticle article=this>>
<</each>>
Easy as that!