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.
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.
- 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
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
- Create an empty project directory to work from
- Initialize a ghost local development instance
- Clone the official Ghost themes github repo
- Create a development branch for our own use
- Link the working theme assets into the development instance
- 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
Don't forget to run
ghost stop ghost-local when finished with theme development.
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
- Visit the Ghost settings menu for the website
- Click the SETTINGS gear icon button
- Choose the Design menu from the WEBSITE section of the settings menu
- Click the Change Theme button
- Click the Upload Theme button
- Select the theme .zip bundle for upload