Add Custom Handlebars Helper to Ghost 5.x

The last version of the Ghost Blogging Platform is 5.2.2.
There have been great improvements in this platform along the time, and running 2.x or 3.x means to have no longer security updates or new features available.
You can check the version related changes here.

Add a custom handlebars helper

The helper code keeps mostly the same from 1.x versions. Here it is an example of a simple helper:

// Compare Helper
// Compare two variables
module.exports = function compare(a, b){

    return a === b;

};

Save the helper in a file having the same filename as the method name (compare.js) into:

current/core/frontend/helpers/compare.js

In case your theme is already uploaded and activated, that’s all!

Do not forget to restart your ghost instance to load the new helper

---

Register custom helper for theme activation

Ghost makes use of a template validation engine called gscan. The gscan engine still doesn’t recognize the new helper just by being present at current/core/frontend/helpers/.

You have a couple of options here:

Add helpers after theme activation

Add the helpers to your theme, but comment out the lines with your custom helper before uploading or activate the theme. Then, inside the production environment, comment out the selected lines again.

This will bypass the gscan checks during activation.

Register helpers into gscan

You could edit gscan to recognize the helper.

Inside your production node_modules dir, find gscan. Inside a path like node_modules/gscan/libs/specs, edit the file v1.js, you’ll find the declaration of the knownHelpers array at the beginning of the file.

knownHelpers = [
    // Ghost
    'foreach', 'has', 'is', 'get', 'content', 'excerpt', 'title', 'tags', 'author', 'authors', 'img_url', 'navigation', 'pagination',
    'page_url', 'url', 'date', 'plural', 'encode', 'asset', 'body_class', 'post_class', 'ghost_head', 'ghost_foot',
    'lang', 'meta_title', 'meta_description', 'next_post', 'prev_post', 't', 'twitter_url', 'facebook_url', 'reading_time',
    // Ghost apps
    'input_email', 'input_password', 'amp_components', 'amp_content', 'amp_ghost_head', 'subscribe_form',
    // Handlebars and express handlebars
    'log', 'if', 'unless', 'with', 'block', 'contentFor', 'each', 'lookup'
    // Registering these will break template compile checks
    // 'blockHelperMissing', 'helperMissing',
];

Add your helper’s name to the array and it should be now recognized by gscan.

knownHelpers = [
    // Ghost
    'foreach', 'has', 'is', 'get', 'content', 'excerpt', 'title', 'tags', 'author', 'authors', 'img_url', 'navigation', 'pagination',
    'page_url', 'url', 'date', 'plural', 'encode', 'asset', 'body_class', 'post_class', 'ghost_head', 'ghost_foot',
    'compare', // <--
    'lang', 'meta_title', 'meta_description', 'next_post', 'prev_post', 't', 'twitter_url', 'facebook_url', 'reading_time',
    // Ghost apps
    'input_email', 'input_password', 'amp_components', 'amp_content', 'amp_ghost_head', 'subscribe_form',
    // Handlebars and express handlebars
    'log', 'if', 'unless', 'with', 'block', 'contentFor', 'each', 'lookup'
    // Registering these will break template compile checks
    // 'blockHelperMissing', 'helperMissing',
];

You are now ready to use a theme with custom helpers in Ghost 5.x versions.

Have fun!