How to get started with custom theme development in Ghost

Since I am faced with this task myself, I figured I might as well document it as I go along. So here are my notes on the process.

Here are my points of departure:

  • I run my production instance on a small home server running Ubuntu
  • I don't want to remote to my server and do development there

My plan, then, is to install another instance of Ghost locally on my windows machine so I can test out how something works locally before deploying it.

Ideally I'd like to work in Visual Studio Code, as it's platform neutral and I am used to it. I should probably also do a git repo just in case.

Please note: This is a work in progress, so I will return to this as I learn stuff and update it.

Preparing the environment

To prepare the local environment:

I personally had to do some housecleaning because Ghost only works with specific versions of nodejs, and the one I had installed was too new. In the end it all worked out.

Once the install process for Ghost is finished, you can access the instance on http://localhost:2368/ghost. Do that, then create a test account and log in.

Download and install theme

Now you install the theme you want to customize locally - you can find some themes here:

Ghost Themes - The Marketplace
Discover beautiful professional themes for the Ghost publishing platform. Custom templates for magazines, blogs, news websites, content marketing & more!

Download the theme - it will save a zip file to your disk - then open you local instance of ghost and apply it.

In your terminal, path to \content\themes\name-of-theme-you-just-applied, then type code . to open the folder in Visual Studio Code.

Modify the theme

Ok, so you now have access to all the theme files and can edit them to your heart's content. But that's daunting, right?

Luckily Ghost is well documented - so:

Ghost Handlebars Themes - Building a custom Ghost theme - Docs
Our handlebars theme templating framework works with the Ghost API to build flexible publishing websites. Get all the tools you need to start building your custom theme here!

Applying the Theme

Applying the theme is pretty easy - you just have to make sure you've given it a custom name and so on, and then upload and apply the theme to your production instance.