In this tutorial we'll explore the basics of a Ghost theme, focusing on file structure and organization.
Ghost themes use the Handlebars templating language, which generates server-rendered HTML and delivers it to the browser. Ghost uses express-hbs under the hood to power theme helpers and additional Handlebars features.
Basic Ghost Theme Structure
This is the most basic structure for any Ghost Theme:
├── /assets
| ├── /css
| ├── /fonts
| ├── /js
├── /partials
├── default.hbs
├── index.hbs [required]
├── post.hbs [required]
├── page.hbs [optional]
└── package.json [required]
All assets such as styles (css), fonts and js should be added in the /assets directory. Actually there is a {{asset}} helper provided by Ghost to help with asset management.
Using the asset helper:
// General usage:
{{asset 'asset-path'}}
// Example usage for site logo
{{asset 'images/site-logo.jpg'}}
(Learn more about the asset helper.)
The /partials folder is great for parts of templates that will be used multiple times without duplicating the code and making maintenance easier.
Using the partials folder:
{{> "partial-name"}}
An example where partial templates come in handy is for post cards, looping over a list of posts and generating a specific layout for these:
{{#foreach posts}}
{{> "post-card"}}
{{/foreach}}
Next, let's take a look at the templates.
Basic Ghost Templates
The most important ones are index.hbs and post.hbs as these ones are
required for any ghost theme to be valid.
Common templates used in Ghost Themes:
default.hbs- it's the base template that contains the most basic parts of HTML that should be on every page (<html>,<head>or<body>).index.hbs- a required template that usually renders the index page of the sitehome.hbs- an optional template to render the home page of the site (if not provided index.hbs is used instead)post.hbs- a required template for rendering a single post ({{#post}}helper is used access and output post details).page.hbs- an optional template for static pages ( If it's not present then post.hbs will be used). Check out this tutorial on how create custom pages for your ghost themecustom-{{template-name}}.hbs- an optional custom template that can be selected in the admin for posts and pages.tag.hbs- an optional template for tag page.author.hbs- an optional template for author page.error.hbs- an optional theme template for errors (ex. accessing a not existing page)
There is also a package.json file.
This is a required file that provides basic information about the theme, plus configuration values that Ghost reads (like how many posts to show per page and what responsive image sizes to generate).
Example package.json file:
{
"name": "your-theme-name",
"description": "Add some description fo the theme",
"version": "1.0.0",
"engines": {
"ghost-api": "v5"
},
"config": {
"posts_per_page": 10,
"image_sizes": {
"xs": {
"width": 100
},
"s": {
"width": 300
},
"m": {
"width": 600
},
"l": {
"width": 1000
}
}
}
}
Note
The exact ghost-api value depends on what your theme supports. Use the latest version your theme is compatible with, and validate using GScan.
Membership templates
Starting with Ghost 3.0 you can turn your site into a membership and subscription based publication. For this your theme requires additional files to be included:
├── /members
| ├── account.hbs
| ├── signin.hbs
| ├── signup.hbs
A new directory called members should be created with the above 3 files.
account.hbs - is the template to render a logged in user account page
signin.hbs - is the template to rendering the sign in page
signup.hbs - this template will render the sign up page
After the templates are created you have to tell Ghost where these files can be found, and you can do that using routes.yaml. Read more about routing.
An example of routes.yaml file:
routes:
/signup/: members/signup
/signin/: members/signin
/account/: members/account
collections:
/:
permalink: /{slug}/
template: index
taxonomies:
tag: /tag/{slug}/
author: /author/{slug}/
That's it for an overview about the structure of Ghost Themes. You can dive deeper in the topic in the official Ghost Docs.