In this article I will show you one possible workflow for Ghost theme development, to customize your blog by altering Ghost's default theme.
The Ghost CMS is pretty well documented. But I think the documentation for theme development is a bit unstructured and unclear. For Example, LiveReload is not available by just starting Ghost in development mode. You have to put some additional effort into it ...
As always I am using Linux for my tutorials, so watch out for the used directory paths and change them accordingly, so they work with your OS.
For theme development it makes sense to create a local installation of Ghost.
To do so, install a supported version of Node.js and use
npm to install Ghost globally on your development machine:
npm install ghost-cli@latest -g
npm install gulp-cli gscan -g
If the installation process succeeds you can skip the next section.
Used versions for this tutorial:
- Ghost: 3.13.4
- Node.Js: 12.16.2
- NPM: 6.14.4
- Gulp-CLI: 2.2.0
- gscan: 3.5.3
Error often occur when performing the simplest tasks. When I tried to install the necessary tools for theme development, I encountered this error:
gyp WARN EACCES user "nobody" does not have permission to access the dev dir "/root/.cache/node-gyp/12.10.0"
There are two ways to resolve this error:
- I haven't tested it myself, but if you take the message by its word, you could create the user
nobodyand give it permission to access
- The approach I took is to change
npm’s default directory, which is also recommended by the
Changing the default directory of
npm also changes some of its behavior when using it. Every Node.Js package you will install globally with your current user, will be available only to this user. Furthermore, you will no longer need the
sudo command to install Node.Js packages globally.
To change the default directory of
npm, create a new global directory:
$ mkdir ~/.npm-global
npm about this directory:
$ npm config set prefix '~/.npm-global'
$PATH variable with this directory path, by editing the
~/.profile of your user. Create the
~/.profile, if it does not exist.
Add or edit the following line:
In the last step we have to tell the current shell about the new
$ source ~/.profile
For me that did the trick. Retry to install the packages that caused this error. Everything should work now.
Preparing a Local Project
Next we will prepare a local instance of Ghost which we will use, to work on our theme.
A local project can be easily set up:
$ mkdir ghost_local $ cd ghost_local $ ghost install local
ghost install local command finishes, the output will tell you where you can access your local Ghost instance:
$ ghost install local ✔ Checking system Node.js version ✔ Checking current folder permissions ✔ Checking memory availability ✔ Checking for latest Ghost version ✔ Setting up install directory ✔ Downloading and installing Ghost v3.13.4 ✔ Finishing install process ✔ Configuring Ghost ✔ Setting up instance ✔ Starting Ghost Ghost uses direct mail by default. To set up an alternative email method read our docs at https://ghost.org/docs/concepts/config/#mail ------------------------------------------------------------------------------ Ghost was installed successfully! To complete setup of your publication, visit: http://localhost:2368/ghost/
We can see that the instance is hosted at http://localhost:2368/ghost/. Before messing around with the theme, we have to set up the CMS like we would, if this was the production environment. Open http://localhost:2368/ghost/ and follow the provided instructions to set up the administrator user.
As soon as you are greeted by the admin panel, you can already stop the instance.
Stop the Ghost instance by running:
$ cd ghost_local $ ghost stop ✔ Stopping Ghost: ghost-local
You can watch the current state of all of your ghost instances by running the
ghost ls command.
In this section I will finally show you how you can start editing the default Ghost theme. First we will install the necessary browser extension to enable LiveReload, so we don't have to manually refresh the page every time we change something about our theme. The ghost process which starts automatically after we instantiated our local ghost project hides its output from us. In the second step we will make this output visible to make debugging easier.
Start by installing the LiveReload extension for your browser. I will use Firefox in this tutorial, but it really shouldn't make a difference for any other browser.
If you use Firefox you can get the LiveReload extension from the official Add-Ons-Page. Somewhere in your browser you should now find this button:
Later this will activate the functionality to automatically reload the page as soon as we change our Ghost theme.
You have to know, that a classical Ghost theme can be seen as a Node.Js project by itself. I will use the default "Casper" theme as an example.
ghost_local project directory navigate to the Casper theme and run
# in ghost_local $ cd current/content/themes/casper $ npm install
The next and last two steps are to start the Ghost instance in development mode and run the Ghost theme project. Open two terminals.
In the first terminal we run our Casper theme project using the
In the second terminal run Ghost in development mode by entering:
Open http://localhost:2368/ and activate your LiveReload browser extension:
Everything you edit in
ghost_local/current/content/themes/casper will now trigger an automatic reload of your page.
Below you can see the full setup in action:
- The right side of the screen show the Ghost landing page and activated with LiveReload extension.
- On the left side you can see the code editor with the opened
- Below the editor you can see the two terminals with the running Ghost instance (left) and the running theme project (right).
As soon as I add the
<h1> tag to
index.hbs and save the file, gulp recognizes the change, rebuilds the project, the LiveReload extension refreshes the page, and we can see the altered theme.
Shipping Your Theme
In the beginning we installed
gscan to check our theme for any errors. So lets use it.
gscan on your altered "Casper" theme:
$ gscan themes/casper Checking theme compatibility... ✓ Your theme is compatible with Ghost 3.x
gscan gives us the green light, it's time to bring out theme into our production environment by creating a ZIP file of it. Creating this ZIP file is fairly easy:
$ cd ghost_local/current/content/themes/casper $ npm run zip
You will find the ZIP file in the
Open the admin panel of your production instance, open the designs tab select
Upload a theme and upload your prior created ZIP file.
If everything went well, your theme should now be visible in your production environment.
This tutorial showed you how you can use the default "Casper" theme to get started with theme development. Furthermore, you've learned how to scan your theme for errors and ship your developed theme to production.
I hope you enjoyed this tutorial and I will see you in the next one!