What is Ghost?

Ghost is an easy, simple to use publishing platform. At it’s core, it’s effectively a CMS built for publishing. We’ve used it in the past with other companies and projects to run blogs. We’re using it for that exact same purpose again at Slingshot Labs. Ghost powers the blogging portion of our website, which is built on Webflow.

Ghost is fully open source, which means you can use it for free if you want to deploy it yourself. Ghost also offers a hosted option called GhostPro. We use the Basic tier, which is pretty affordable at $29/month.

Ghost offers a freely available default theme called Casper. As default themes go, it’s a really high quality standard, unlike a lot of the starter templates most tools offer.

While we were impressed by the starting position of the Casper theme, it’s pretty natural to want to make modifications to make the theme suit your business and use case. At Slingshot, this was definitely the case. As we are running Webflow and Ghost side-by-side, we wanted to normalize certain elements, including the navigation and footer to give people visiting our website a seamless experience.

The ghost docs are pretty strong in general, but we didn’t see a combined guide that covered getting started with Ghost and took you all the way through customizing a ghost template. There are decent resources out there that handle parts of this journey, and do so in more detail than we’ve done, but nothing touched on the whole process.  So we’ve put together a single step-by-step guide that covers:

  1. Installing Ghost
  2. Customizing the Casper theme locally
  3. Installing your customized theme into your hosted Ghost site

Installing Ghost

As mentioned, there are really good resources on each piece of this, but nothing that ties the whole together. Checkout this resource, provided in the Ghost docs, about installing Ghost locally. We’re going to include the steps here to provide the one stop shop to getting started with Ghost.

1. Install Ghost-CLI

npm install [email protected] -g

2. Install Ghost

You’ll want to cd into whatever directory you want to install Ghost.

ghost install local

3. Make sure you are using the LTS version of Node.

Depending on which version of Node you’re running, you may see an error.  /If you want to see which versions of Node ghost supports, see here./

The fix is pretty easy if you run across this error. You can use something like Node Version Manager (NVM) to install specific versions of Node and switch to the supported version. To install NVM:

a. Install NVM

b. Install the LTS version of Node (which Ghost supports)

nvm install --lts

c. Tell NVM to use the LTS version

nvm use --lts

You should see something like this in your terminal, which means you’re now running the right version of Node.

Whether you hit this problem during the installation process or just trying to run ghost for development purposes, once you’ve switched into the appropriate version of Node, you should be able to re-run whatever command you were running to complete that process. In this tutorial, we were trying to install Ghost. So we’ll re-run the install command:

ghost install local

You should see the following in your terminal:

And following the link to http://localhost:2368/ghost/ should show the following user onboarding to the Ghost Admin.

You’ll want to complete the guided onboarding, filling out Account details for local development. These details can be whatever you want them to be and do not need to match your hosted Ghost account (if you’re a GhostPro user). I would skip over the ‘Invite Staff Users’ as part of this flow.

You should now see the standard Ghost Admin running at http://localhost:2368/ghost/#/site.

You will want to replicate your settings from your hosted Ghost Admin into your local Admin. This is an important part of the local development process, especially when modifying the navigation and other elements that are impacted by settings in the admin.

Congratulations! You now have Ghost running locally and you’re ready to start your theme development.

Customizing the Casper theme locally

The base installation of Ghost includes the Casper theme. If you’re working with Casper you can simply start here. If you’re working with another theme, you can download it into this directory. If for some reason, Casper has been deleted from this directory, you can download it by:

1. From the root directory of your Ghost installation, you’ll want to cd into content/themes. Then run:

git clone https://github.com/TryGhost/Casper.git

2. At this point, you’ll want to cd into the Casper directory and run yarn install.

You should get  something that looks like this:

If you hit a version error, run nvm use --lts and then repeat the yarn install command.

3. Now, run yarn dev.

You should get something that looks like this:

Every time you make a change to one of the files within your Casper theme, you’ll see relevant files reloaded and served from here. Once that’s complete, you’ll be able to see those changes at http://localhost:2368/ghost/#/site.

4. Modify one of your theme files.

You’ll want to open the Casper theme files in whatever code editor you use. I use atom, so I would cd into the Themes subdirectory and run atom Casper to open the theme files in Atom. If you don't use Atom, you'll want to open the Casper theme files in your code editor of choice.

You can then make whatever changes you want. For example, adding color: #5334F1 to .post-card-title in screen.css, under Assets/CSS.

Once I’ve saved this change in my code editor, I should see activity on the terminal I’m serving my theme from:

And I should see this update live at http://localhost:2368/, like this:

As you can see, my Post Titles are now a bright purple, which is the #5334F1 color we set above. I wouldn’t necessarily recommend using this Title color with the light blue subtitle that comes standard in Ghost but these decisions are for you to make!

Installing your customized theme into your hosted Ghost site

When you’re happy with the changes and ready to upload them to your site, cd back into the Casper subdirectory at Content/Themes/Casper.

1. Run yarn zip.

You’ll see something that looks like this:

2. Navigate to the dist subdirectory via your finder or run open dist and your zip file should be sat there.

3. Last but not least, navigate to your hosted Ghost.org Admin. Under the Settings header on the sidebar, select the Design page.

4. Scroll to the bottom. And select ‘Upload a theme’. Once your theme is uploaded, click ‘Activate’ and your theme is now live!

We hope this was helpful! Give us a shout if you have any questions or leave a comment if you approach any of the above differently.