Hello everyone,
This is issue number #10 of Ghost Tips & Tricks. Brought to you by Aspire Themes. Premium and high-quality Ghost themes.
I want to talk about what makes a Ghost theme, the theme structure, which files are essential, and what each file does.
Handlebars
First, Ghost uses Handlebars as a template language; that’s why the theme file extension is .hbs. For example, index.hbs, post.hbs or author.hbs. There is no need to install Handlebars in a Ghost theme; it is part of Ghost.
Let’s take a quick example of how Handlebars integrated with Ghost to output data from a Ghost website.
Suppose we want to output your post content, we can use the content helper enclosed by double curly braces {{ }}, which will give us a Handlebars expression. So, adding the complete {{ content }} expression to a theme will generate the post content.
In addition to Handlebars, Ghost uses the express-hbs library to extend Handlebars features. For example, to add partials and layout support.
File Hierarchy
An essential concept to how a Ghost theme works is how Ghost chooses which file to use to render the content. For example, for the website Homepage, Ghost first checks if a theme file called home.hbs exists; use it; if not, Ghost will look for another file, in this case, the index.hbs file.
Another example for the Author page, Ghost will look for the author.hbs first and use it if it exists. If not, Ghost will use index.hbs.
From the two examples above, we can see that the index.hbs file is necessary for any Ghost theme.
Essential Files
The package.hbs, index.hbs, and post.hbs files are three essential files in any Ghost themes.
Let’s consider that we have a theme called anatomy; the file structure would be.
anatomy
|__index.hbs
|__post.hbs
|__package.json
Let’s see each file in more detail.
➊ package.json
The package.json is a JSON file with the .json extension. It contains name/value pairs of data. What kind of data can we add?
- Theme name and version
- Theme author data
- Ghost and Content API versions
- Theme configuration like how many posts per page to display
- Dynamic image sizes for uploaded images
- Theme NPM dependencies
Some of this data is visible on the admin side. For example, when you go to your Ghost admin Design >> INSTALLED THEMES section, you can see a list of the available themes on your blog. For each theme, you can see the theme name and version.
The name and version are available as name/value pairs in the package.json file.
The name field is, of course, the name of the theme. The version is the theme version.
Let’s apply this for the anatomy theme we have and add the following data to the package.json file.
{
"name": "anatomy",
"version": "1.0.0"
}
Now, Ghost will use this information to list the theme under the INSTALLED THEMES section with anatomy as the theme name and 1.0.0 as the theme version.
By adding the package.json file, we now created our first theme, and it is visible in the available themes list. But if we tried to activate this theme, Ghost will throw a fatal error complaining that the other two files are missing, the index.hbs, and post.hbs.
➋ index.hbs
The index.hbs is the second essential file used to show a list of posts.
We talked about hierarchy earlier in this post and mentioned that Ghost would use the index.hbs for the Author page to list the author’s posts if the author.hbs file does not exist. In addition to the Author page, Ghost will use it for the Tag page if the tag.hbs file does not exist.
➌ post.hbs
The third essential theme file is post.hbs, which outputs the post details.
After adding both index.hbs and post.hbs, we can now activate the theme. If you went to the website homepage, you would see an empty page. However, while activating the theme, we will see some missing CSS classes and package.json missing properties. But as a starting point and at this stage, we were able to activate the theme with the must-have files.
That’s all that I wanted to share today, and I hope you find this post helpful.
Checkout previous parts of the Ghost Tips & Tricks series:
- Ghost Tips & Tricks #1 / Show Publish Date in the day time with AM and PM format
- Ghost Tips & Tricks #2 / Ghost Admin Right to Left (RTL) Support
- Ghost Tips & Tricks #3 / Deploy Your Ghost Theme Using Github Actions
- Ghost Tips & Tricks #4 / Create a Tags List Page
- Ghost Tips & Tricks #5 / Create an Authors List Page
- Ghost Tips & Tricks #6 / Change Casper Theme Fonts Using Google Fonts
- Ghost Tips & Tricks #7 / Tools I Use to Develop, Edit and Deploy Ghost Themes
- Ghost Tips & Tricks #8 / Membership Troubleshooting Tips
- Ghost Tips & Tricks #9 / Ghost Tags - Practical Examples to Use in Your Theme
Also, check out my Ghost Websites Inspiration and Ghost Newsletter series.
Stay safe!
Ahmad