In this tutorial we will explore the basics of a Ghost Theme, more specifically the file structure and organization.
Ghost themes use the Handlebars templating language, this generates a static HTML server side and delivers it to the browser. Additionally express hbs library is used to for adding additional 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 some basic information about the theme. You can set the Content API version for the theme, how many post should be shown per page, and the responsive image sizes that will be generated when you upload an image in Ghost Admin.
Example package.json file:
{
"name": "your-theme-name",
"description": "Add some description fo the theme",
"version": "1.0.0",
"engines": {
"ghost-api": "v3"
},
"config": {
"posts_per_page": 10,
"image_sizes": {
"xs": {
"width": 100
},
"s": {
"width": 300
},
"m": {
"width": 600
},
"l": {
"width": 1000
}
}
}
}
Ghost 5.0 Theme Structure
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 for this routes.yaml file can be used. 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.