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:

  1. 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. 
  2. 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.
  3. 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>>
            <p>Article is featured</p>
          <<else>>
            <p>Article is not featured</p>
          <</if>>
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>>
            <h1>This is a public article</h1>
          <</unless>>
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>>
            <p><<this.title>></p>
            <small><<this.description>></small>
          <</each>>
eq Checks if the two numbers passed are equal
<<#if (eq this.meta.num_articles 1)>>
            There's one article in this category
          <</if>>
gt Checks if the first number is greater than the second
<<#if (gt this.meta.num_articles 1)>>
            There's more than one article in this category
          <</if>>
lt Checks if the first number is less than the second
<<#each this.articles>>
            <<#if (lt @index 5)>>
              <img src="<<this.author.profile_image>>">
            <</if>>
          <</each>>
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)>>
            <p>Some text</p>
          <</unless>>
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-")>>
            <i class="fa <<category.icon>>"></i>
          <<else if (hasPrefix category.icon "http")>>
            <img src="<<category.icon>>">
          <</if>>
hasSuffix Checks if a string ends with a string suffix
Suffix ends in fix:<<hasSuffix "Suffix" "fix">>
 
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)>>
            <h3><<this.title>></h3>
          <</each>>
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.category_id this.category_id)>>
            <p>This is a parent of the displayed category</p>
          <</if>>
i18n Find the current language version of a given internationalization key, falling back to the second string
This category has <<category.meta.num_articles>> <<i18n "articles" "docs">>
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), categoryarticlesearch.
<<#page "home">>
            <<> superFancySearchBar>>
          <<else>>
            <<> boringOlSearchBar>>
          <</page>>

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. <<> contactLink class="btn btn-secondary">>
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). <<> categoryBreadcrumbs linkify=true>>
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. <<> hdFooter>>

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!

Inline partials must be at the top level, not indented, and not nested inside any other markup. A good place to declare these would be header.hbs

What did you think of this doc?