Hi there! Today I will walk you through how you can add custom HBS helpers to your ghost blog to develop your ghost blog theme.

HBS helper functions are function that allow you to manipulate HTML inside your ghost blog themes .hbs files. However, the helpers provided by Ghost blog out of the box are limited.

For example, if you want to split text based on a keyword, a helper might come in handly. Here is how you create it!

PS this guide assumes that you know how to setup a Ghost blog using your own server through the open source git modules.

Step 1: Create a helper function

First off, lets create a helper function by going to:

[your_ghost_blog_server]/core/frontend/helpers

There you will create a new file with a name of the helper function you want to create. In my case, I am creating a split function, so I'll call the file as split.js.

helpers/split.js

module.exports = function split(text) {
    // eslint-disable-line camelcase
    var t = text.split("-");
    return t[1] + " <br/> " + t[0];
};

Tip: make your function do whatever you'd like using arguments passed.

Step 2: Add the helper function to the theme engine

THIS STEP IS NOT REQUIRED IN NEWER VERSIONS OF GHOST ;)

To use the newly created helper function, you will need to add it to the engine for Ghost theme to pick it up. Go to:

[your_ghost_blog_server]/core/frontend/services/theme-engine/handlebars/helpers.js

Once there, register the new helper function on line 43

registerThemeHelper("split", coreHelpers.split);

Step 3: Use the customer helper function in your theme!

Once registered, you can use this custom helper in your HBS theme!

.hbs file

<div>
    {{split custom_excerpt}}
</div>

Step 4: Override the test that says Templates must contain valid Handlebars

This works like a charm, however, the ghost compiler will still complain about using invalid handlebars with an "Oops, You seemed to have used invalid Handlebars syntax." which is pretty annoying.

I beleive you should be able to override this check and add your custom helper to the list of checks, however, I am still figuring out how to do this. (2021.9)

Hint: you'll need to clone and modify the "gscan" ghost scanner module. For now I am just ignoring the error.

If you know how, let me know :)


That's all you need to setup a new custom HBS helper function. If you have any questions you can reach out on my Twitter.

Best of luck!