Ghost Custom Theme Development, Deployment and Maintenance

This post serves as a guide and discussion of my current approach to the Ghost theme for this and other websites. Low maintenance is my objective with this approach.

Objectives

Low maintenance over time is the primary objective here. Theme authoring, deploying Ghost and keeping it updated, and keeping the theme updated as ghost's theme engine evolves through major version changes.

Overview

• Local development is trivial thanks to ghost-cli
• Use an official open-source official theme as a starting point
• Development is managed by branching off the official ghost theme repository
• When Ghost updates their official theme, easily incorporate those changes with git rebase

Preresiquites

• A supported version of Node.js, preferably using node version manager (nvm)
• yarn
• ghost-cli
• git

Theme Development

Choose a Base Theme

Browse the official Ghost themes here.

I recommend starting with an official theme instead of a third party one. The official themes have been actively maintained by Ghost across minor and major platform updates. When ghost makes breaking changes to theme development, or releases new features, we can easily incorporate those updates in our custom theme as described later in this guide. If we choose a third party or commercial theme, we are at the mercy of the third party to keep the theme up to date.

For the examples in this guide, we have chosen the Journal Theme.

Prepare The Environment

.
└── ghost-dev
   ├── ghost-local  # local ghost install
   └── ghost-themes # clone of ghost themes git repository

1. Create an empty project directory to work from
2. Initialize a ghost local development instance
3. Clone the official Ghost themes github repo
4. Create a development branch for our own use
5. Link the working theme assets into the development instance
6. Run the theme

# Create an empty project directory
mkdir ghost-dev
cd ghost-dev

# Initialize a ghost local development instance
mkdir ghost-local
cd ghost-local
ghost install local
cd ..

# Clone the official ghost themes repo
git clone [email protected]:TryGhost/Themes.git ghost-themes

# Create a custom dev branch for our customizations
cd ghost-themes
git checkout -b mjacdev/journal

# Link the theme assets into our local ghost instance
cd ghost-themes
yarn symlink --theme Journal --site ../ghost-local

# Restart ghost to load the new theme
cd ../ghost-local
ghost restart

# Run theme development server
# While running, changes to theme source files are
# compiled for use by running ghost instance
cd ../ghost-themes
yarn dev

Design a Theme

Use the local copy of ghost and design the theme! Check out the Ghost Themes Docs for more on theme design. In the Ghost settings menu, use the Advanced button to select your theme.

Commit changes to the local git repo as you go. For example:

git log --oneline
18096a93 Expand on prism syntax highlighting
533b3fff Add social icions, format search button
def590e8 Add WHOIS section to homepage
...

Keeping Theme Up To Date

Use git rebase to incorporate updates made by ghost to the official theme into the customized version.

# Pull changes to the original theme from github
git pull origin/main

# Rebase modifications on top of those new changes
git checkout mjacdev/journal
git rebase origin/main

Clean Up

Don't forget to run ghost stop ghost-local when finished with theme development.

Deployment

Create Theme ZIP File

The Ghost themes repo provides a helper command to create a theme .zip file. The file can be uploaded directly in the ghost settings menu to apply or update a theme.

# Create theme zip bundle
yarn zip --theme Journal

Upload Theme to Ghost Server

1. Visit the Ghost settings menu for the website
2. Click the SETTINGS gear icon button
3. Choose the Design menu from the WEBSITE section of the settings menu
4. Click the Change Theme button
5. Click the Upload Theme button
6. Select the theme .zip bundle for upload