Custom Helper Functions For Ghost

Sprinkling your own touch of magic on your blog could open doors to a lot of custom functionalities. Helper functions are used to share a bit of code throughout your website or blog. For this, we'll focus on our Ghost Blog.

Ghost has its own helper functions readily available for us to use on our frontend. There are times when we want to add own our functionality. Sadly, and at current time of writing this post, it is not possible to add custom helper functions to your Ghost Blog without modifying the Ghost's core. This means you will need to keep track of all changes that you've made to the core when you upgrade, as doing an upgrade will remove any added code you have written.

Today, we'll show you a clean way to add custom helper functions to you Ghost Blog. Yes, this means to edit the core 😿 Luckily for us, we'll only make one core edit which enables us to add as many helper functions as we need. Let's not get too crazy here. We'll never need too many helper functions.

Helper functions live on the server. This means you won't be able to target any DOM elements ie document.getElementById(elementId) . Your helper function would error that document is undefined. Good! Now the fun part:

Inside our /core/server/helpers/index.js we need to change things up a tiny bit. Not needed but it could possibly lead to code smell. We'll now simplified our registerAllCoreHelpers()

// Merges new helpers with the already declared coreHelpers
coreHelpers = Object.assign(coreHelpers, require('../../../content/helpers/'));

// Registering coreHelpers and our new helpers
registerAllCoreHelpers = function registerAllCoreHelpers() {
    Object.keys(coreHelpers).forEach((key, index) => {
        registerThemeHelper(key, coreHelpers[key]);
    });
	
    // Async theme helpers
    [...]
})

Up next, create a helpers folder inside /content/ and inside the JavaScript files with the name of your helper and also inside an index.js.

// /helpers/hello.js
module.exports = function hello(name) {
  return `Hello, ${name}!`
}

Up next comes is the magic inside index.js

const hello = require('./hello')
// You could also require more!

// Combine and export with good 'ole Object.assign()
module.exports = Object.assign({hello /**, bar **/})

Back inside our /core/server/helpers/index.js, we required our combined helper functions with require('../../../content/helpers/') then merged inside the object, coreHelpers. There's one issue with this that I haven't looked into properly. When you call your custom helper function (from view, ie: inside post.hbs), with a param, then restart your server, you'll get an error:

NAME: ThemeValidationError
MESSAGE: The currently active theme "casper" is invalid.

"Templates must contain valid Handlebars\",\n\t\t\"details\": \"Oops! You seemed to have used invalid Handlebars syntax...

However, our function still works! At the time of writing, I'm using Ghost version 2.2 and I haven't tried upgrading nor have I looked into it deeper. I'm pretty confident that Ghost experts out there can spot a file I've missed to edit or I'm not merging the functions properly with Object.assign(). For now, and until Ghost gives us the ability to add custom helpers, this is one of your best shots of having custom helper functions in your Ghost Blog. Until then, ✌🏻