How to build on top of the Casper theme in Ghost

How to build on top of the Casper theme in Ghost

This blog runs on the Ghost platform, and I've done a bit of customization to the styling. Nothing major.

I was mildly surprised when I ran a ghost update the other day and suddenly my custom themes and scripts were just gone! Luckily I use DigitalOcean (a great provider, if you happen to be looking for one) with backups enabled, and I had a backup from just a couple days before. I rolled back, verified my styles and customizations were present, then ran ghost update again. Wiped out.

In retrospect, this makes sense. There are going to be updates to Casper, the default Ghost theme, and how should they reconcile that with any local changes I've made? They can't reasonably, so they just overwrite it. WordPress had the concept of child themes, which allowed for extending a base theme, so I attempted to do something similar with Ghost.

If you find yourself wanting to use most of the Casper theme, but with some customizations (and you don't want to shove them all into the "Code injection" tab in the ghost admin screen), then here's what I did:

Fork the theme

Fork the default Casper theme to your own GitHub account.

Clone it locally

Clone it locally using one of these:

git clone git@github.com:YOUR-USERNAME/YOUR-FORKED-REPO.git

git clone https://github.com/YOUR-USERNAME/YOUR-FORKED-REPO.git

Rename the directory on your local machine so it's different than the default theme name - something like Casper-YOUR-USERNAME. This is necessary when uploading the child theme later - the name cannot be the same as the default.

Modify it to your liking

Make any changes you'd like to the theme. I made small tweaks to add more social icons and whitespace, change the blockquote style, use Prism.js for code styling, etc.

Package and upload it

Compress the local directory so you end up with a Casper-YOUR-USERNAME.zip file, and then use the Design tab under settings in the Ghost admin to upload your new theme. Activate it (it should prompt you). Restart Ghost using ghost restart if you don't see the changes applied (but they should be).

Fetch latest official changes, periodically

To avoid missing out on future updates to the default Casper theme, keep your fork up to date (don't forget to commit your changes first).

cd into/cloned/fork-repo
git remote add upstream git://github.com/ORIGINAL-DEV-USERNAME/REPO-YOU-FORKED-FROM.git
git fetch upstream
git pull upstream master
git push

If you're a fan of git aliases, after you've run the above once you could add something like this to your .gitconfig file:

updatecasper = !cd your/casper/location && git fetch upstream && git pull upstream master && git push

NOTE:

This method of updating my local fork worked perfectly fine for me, but you may also want to checkout the official doc on Syncing a fork which suggests a git merge instead of a git pull. There's also a comment under the gist I linked to above, that suggests a way to keep forks up-to-date all through GitHub.