Basics of Ghost Theme Development: Handlebars, Theme Structure and Contexts

Have you ever finished a project and thought, “I wish I knew this before I started”? It happens to everyone! This tutorial will share important tips and insights you need before creating a Ghost theme. We’ll focus on three main areas:

1. Handlebars: What is Ghost’s templating language, and what does that mean?
2. Theme Structure: How a Ghost theme is set up and the three key files you need.
3. Using Contexts: How to get the right data when you need it.

By understanding these three basics, you’ll not only see how a Ghost theme works but also be ready to create your custom theme!

What’s a templating language anyways?

First, let’s understand what a templating language is before we dive into Handlebars, which is Ghost’s specific language.

Think of a template like a mold for a cake; it helps shape your site’s data. You use one template for your homepage and a different one for a post page. So, making a Ghost theme is really about creating a bunch of templates. You write these templates using Handlebars, and you can easily recognize Handlebars files because they end with the .hbs extension.

The basics of Handlebars

When you create a Handlebars template, most of it will be in regular HTML, which is the basic code used in almost every website. Handlebars is used when you want to show changing data in your theme. This changing data includes things you enter in Ghost Admin, like your site’s title, navigation links, and the content of your posts. Here’s a simple example of how to show your site’s title using HTML and Handlebars.

<h1>{{ @site.title }}</h1>

Let’s break down each part of this code.

• The <h1></h1> tags are for a main heading in HTML. Nothing special about that.
• The {{ and }} are the Handlebars tags. They tell Ghost that something needs to be done with the data inside. These tags are called “Handlebars” because they look like a mustache. Just like you need both sides of a mustache, you always need to close your Handlebars code with }}.
• @site.title is a special piece of data you can use when creating a Ghost theme. It shows the actual title of your site. “Render” just means to replace something. For example, if your site is called Delicious Cakes, then Ghost will replace <h1>{{@site.title}}</h1> with <h1>Delicious Cakes</h1>. The great thing about this is that if you change your site’s title to Delicious Cakes and Cookies, it will update automatically without needing to change the template.

Before diving into all the cool features of Handlebars, let’s quickly review what we’ve talked about so far.

• A Ghost theme mainly consists of Handlebars templates.
• These templates are processed by Ghost using your site’s data to create HTML that browsers can read.
• Your visitors don’t see any of this; they just enjoy your beautiful site.

Here’s a slightly more detailed look at what we’ve covered earlier.

Ghost Helper Functions

Ghost offers a variety of helpers to assist you in creating your theme. These helpers can display data, manage how things flow, translate text, handle pagination, retrieve extra data, and more. To understand all the possibilities for building a Ghost theme, it’s a good idea to look at the complete list of helpers available.

Let’s see an example of a helper in use. Imagine you’re on your post page. Sometimes you add a feature image, and sometimes you don’t. The {{#if}} helper helps you handle both situations.

{{#if feature_image}}
  Code to display if there is a feature image
{{/if}}

To use the helper, you start with #if followed by the value you want to check. If that value is true or exists, everything between the Handlebars tags ({{#if}}…{{/if}}) will be shown. If the value is false or missing, nothing will be displayed. This approach helps ensure that your theme looks good no matter what content is available.

For example, you can think of it like a light switch: when the switch is on (meaning the value is true), the light (your content) lights up. When the switch is off (meaning the value is false), the light stays off. Casper, a well-known Ghost theme, shows a real-life example of how this works.

The if helper is just one of many tools Ghost offers. By using these helpers, you can create flexible themes that adapt to different situations and explore creative options. In the next section, we’ll see how these helpers come together in the template files that shape a theme.

The structure of a Ghost theme

A typical Ghost theme includes several types of files, but only three are necessary for it to function:

1. index.hbs
2. post.hbs
3. package.json

You can zip these files together, upload the zip to Ghost, and get a working theme. Understanding what these three files do is key to learning about the structure of a Ghost theme. Here’s a quick summary of each one.

index.hbs is a theme’s front door

Let’s start with index.hbs because it’s the main file for your website. By default, this template shows your site’s homepage. Just like a book’s index helps you find different topics, index.hbs helps you organize your posts. When you change the index.hbs template, you can control how the list of posts looks on your Ghost site.

This file is also used for all pages that display a collection of posts, including your homepage and any other pages with posts, as well as tag and author pages. Ghost is flexible, so it’s common to create different templates for each of these pages if you want.

post.hbs is where the content is

The second important file is post.hbs. This file is responsible for showing all individual posts and pages. When you change this template, you can adjust how the content of each post looks on your site.

The main difference between a post and a page is that a post is always part of a collection, while a page isn’t. This means that posts will appear in the list on your homepage, but pages will not. Generally, posts are for articles, while pages are for content like about and contact information.

package.json is the brains of the operation

The last required file is package.json. If you’re familiar with Node.js, you’ll know that this JSON file contains important information about the project, specifically the Ghost theme. This information includes the theme’s name, version, scripts, dependencies, license, and more.

Ghost also uses package.json to set up some features of the theme. Here are the three most common settings you can adjust:

• Posts per page: This setting tells Ghost how many posts to show in a collection. For instance, if you set it to 15, then 15 posts will appear on the homepage.
• Image sizes: Ghost can automatically optimize the images used in your theme, and this setting tells Ghost which sizes to create.
• Custom settings: These allow users to adjust various options from Ghost Admin. For example, in Casper, one setting lets users choose between a serif or sans serif font for the body text.

Together, these three files create the structure of your theme. The first two are made using HTML and Handlebars. Context is what connects everything, and that’s what we’ll explore next.

Getting the right data to the right template with context

The last idea to grasp when working with a Ghost theme is context. Every page in a Ghost theme is associated with a context, which decides which template is used and what data is accessible.

This might sound a bit abstract, so let’s look at a real example. Imagine the Delicious Cakes site has an article about chocolate cake (and not just any chocolate cake, but the most amazing one you’ve ever tasted). This single post falls under the post context. This means it will use the post.hbs template and have access to all the relevant post data, like the title, author, tags, and more.

Here’s a quick overview of the different pages, contexts, and templates in Ghost. A couple of important points about this overview:

• The homepage has multiple indexes. Similarly, if you’re not on the first page of a collection, the paged context will also be included. For example, on /page/2/ of your site, the context will be both paged and indexed.
• If a specific template isn’t available (like author.hbs), Ghost will automatically use a template that is always present.

Page	Context(s)	Template	Fallback template	Data
Homepage	home, index	home.hbs	index.hbs
Collection of posts	Post	post	post.hbs	Post data
Page	page	page.hbs	post.hbs	Page data
Author	author	author.hbs	index.hbs	Author data and post collection
Tag	tag	tag.hbs	index.hbs	Tag data and post collection

To summarize, understanding contexts is crucial because they significantly affect how you build a Ghost theme. Contexts not only decide what data is available and which template to use, but they also work with Handlebars helpers. For more information about contexts and to see the data available in each one, be sure to check the official documentation.

Conclusion

In this tutorial, you learned three key ideas that are important for understanding a Ghost theme:

• Handlebars is the templating language used in Ghost to create templates.
• The three necessary files — index.hbs, post.hbs, and package.json — form the structure of a theme.
• Contexts link your site’s data to the correct template.

If all this feels a bit theoretical, like trying to learn to swim from a book, the best next step is to dive in and start building a custom theme or make some simple changes to an existing one. Check out our guide on installing Ghost locally to help you get started. Our tutorials and documentation are great resources, and our Forum is a friendly place where you can ask questions.