Things I Wish I'd Known Before Creating My Own Ghost Theme

Ghost themes make extensive use of Handlebars.js

Handlebars is a templating language, designed to allow separation between HTML and a data source:

<div class="entry">
  <h1>{{title}}</h1>
  <div class="body">
    {{body}}
  </div>
</div>

Above shows a simple Handlebars template. {{title}} and {{body}} are Handlebars expressions which will be swapped out at runtime with actual data. The rest of the snippet is standard HTML which (along with CSS) provides the structure, layout and design.

For more detail head over to the Handlebars website and do some reading!

A Ghost theme is just a directory

As mentioned previously, a Ghost theme is simply:

• A directory on the file system
• This directory contains multiple Handlebars templates, each with the .hbs file extension.
• The templates work collaboratively to render your blog content.

There’s a recommended file structure for a Ghost theme

Stick to this for great benefit:

.
├── /assets [contains all your static content, e.g. css, fonts, images, javascript]
├── default.hbs [contains common content for every page e.g. header, footer etc]
├── index.hbs [**required** the template for your blog home page]
├── post.hbs [**required** the template for each post]
└── package.json [contains template details e.g. name, version, description]

There are only two mandatory files in a Ghost theme.

A Ghost theme must contain the following two files:

• post.hbs
  • This is the template for an individual post.
• index.hbs
  • This is the template for the blog homepage.

Everything else is optional.

Ghost makes data available to your Handlebars templates by magic

• post.hbs is always passed a post object
  • The post object consists of:
    • id – the post id
    • title – the post title
    • url – the relative URL for a post
    • content – the post content
    • published_at – date the post was published
    • author – an object representing the post author
      • author.name – the name of the author
      • author.email – the author’s email address
      • author.bio – the author’s bio
      • author.website – the author’s website
      • author.image – the author’s profile image
      • author.cover – the author’s cover image
    • tags – an object representing the post’s tags
      • tag.name – the name of the tag
      • You can use the {{foreach}} helper to iterate over the tags
    • Each of these properties can be output using a standard Handlebars expression, e.g. {{title}}. In addition, you can use just {{author}} to output the author’s name:

{{#post}}
<h1 class="post-title">{{title}}</h1>
<p>Published by {{author}} on {{published_at}}</p>
<p>Tags:
    {{#foreach tags}}
        <li>{{name}}</li>
    {{/foreach}}
</p>
<p>{{content}}</p>
{{/post}}

• index.hbs is always passed the posts object.
  • This is a collection of all the post objects in your blog.
  • Again you can loop over these using the {{foreach}} helper:

{{#foreach posts}}
  <h1 class="post-title"><a href="{{url}}">{{title}}</a></h1>
  <p>{{content}}</p>
{{/foreach}}

• All Handlebars templates are passed global blog properties via the @blog object
  • {{@blog.url}} – the blog url specified in config.js
  • {{@blog.title}} – the blog title from the settings page
  • {{@blog.description}} – the blog description from the settings page
  • {{@blog.logo}} – the blog logo from the settings page

There are many Handlebars helpers available

• You’ve already seen {{foreach}}, but Ghost has many other built in helpers to help you build or customize your theme.
• They’re accessed via a Handlebars expression e.g. {{foreach}} or {{content}}.
• You can find the complete list here.

You should use Handlebars inheritance to minimize waste

Handlebars templates can inherit from each other. This really helps to cut down on code duplication/waste:

• {{!< templatename}} indicates extension.
  • The entire output of the current template will be rendered into the {{{body}}} of templatename.hbs.
• {{!> templatename}} indicates injection.
  • The entire output of templatename.hbs will be rendered in situe.

You should read the official Ghost Themes documentation

It’s really good. Go and check it our here.