Ghost Theme Development
Set up local Ghost instance to develop and test theme.
Ghost upgraded their software and changed their Casper theme. I had previously adjusted the theme so I could get the visuals I wanted and add syntax highlighting, so it is time to fix things up. Time to document the pieces I needed to iterate the theme. If you are reading this you may be looking to do the same?
Software
I did this last night under Windows, but since everything is using Node you can just as easily do this on another platform. You need:
NodeJS comes with npm, and you need to install globally other modules with these commands:
npm install -g ghost-cli@latest
npm install -g gulp-cli@latest
npm install -g nodemon@latest
npm install -g gscan@latest
They will provide, in order: Ghost local installation, Gulp automation to recompile your theme as you save, restart the Node server every time you make changes to the theme, and finally a tool to validate the theme.
Setup
Install local copy of Ghost by:
ghost install local
Add theme to the installation using a symbolic link or directory junction, the theme should live under content/themes in its own directory. I forked a copy of Casper and named it casper-fzco.
Then start nodemon under a NodeJS shell and watch for changes:
nodemon current/index.js --watch content/themes/casper-fzco --ext hbs,js,css
In another NodeJS shell, under the directory where your theme source files live, run:
yarn install
yarn dev
You only need to do yarn install once, and it'll pull in all the Node modules it needs and place them under node_modules. With yarn dev every time you save changes to .css, .hbs, or .js files it'll recompile the theme for you.
Once all of this is done you can access the local installation on port 2368, like so:
And see the results of your code changes. It may also help to export then import data from your real installation to make sure the new layout didn't break existing articles.
Update
Once everything is the way you wanted, type:
yarn zip
to create a ZIP archive of your theme. This ZIP file is what you'll upload to your installation.
Version Control
It is usually a good idea to change the version string inside file package.json so that you know which version is running on your installation.
If you are tracking your updates using source control management software then it'll also be useful to ignore files under directories node_modules, dist, and assets/built.
Import Data
In the Setting section of your Ghost administration UI, you can export texts for an existing site as one big JSON file. You can then import all that data into your local testing and development instance. Note that, images are not exported so you will want to save a copy from your live site to help the local instance to simulate the layout.
Accessing Development Instance
Sometimes you want to see your theme in action on a variety of devices, but they will not be able to access the instance hosted on your development machine. To fix that, shutdown the instance and edit a file config.development.json. Keep the url and host server IP addresses consistent, otherwise some scripts will not work; this is because your browser will probably block cross-origin resource sharing.
Missing Assets
I discovered that, after changing one of the .hbs templates my theme stopped working. After some investigation showed that it has to do with the {{asset}} directive; it was inserting a space in front of the resource I was referencing. To work around it, remove the quotes around the href and make sure there is no space in the URI.
