Creating a custom template

One of the most powerful features within the Ghost theming layer is the ability to create custom templates. These templates can then be selected when creating a post, allowing the writer to use a unique layout for their content. This tutorial shows you how to create a custom template within a Ghost theme.

Creating a template file

Before we dive in there's a couple of prerequisites I'd like to explain that themes in Ghost use Handlebars, a templating language that provides access to Ghost content and other common templating benefits.

To begin creating a new custom template, download the currently used theme from Ghost admin. Navigate to the Design view and scroll to the selected theme and click "download" on the right hand side.

Download theme UI in the Ghost admin

Once you've unzipped the theme you can view the theme files inside. Every Ghost theme contains a series of "hbs" files, which stands for handlebars. These files render all your posts, pages, and all HTML in your site.

Theme file structure

Create a new "hbs" file within the root theme folder with the prefix of custom-, in my case I'm going to name the file custom-full-width-post.hbs.

custom-{{template-name}}.hbs

The naming convention for custom templates is important for two reasons; the custom- prefix lets Ghost know that this is a custom template and that it should be selectable in the post settings panel, and everything after the initial dash (-) is used for the name in the select UI.

Theme file structure with new custom template added

In this example, custom-full-width-post.hbs will show up in the post template setting as "Full Width Content".

Using Handlebars

Now that a template file has been created you can get started and put some code inside it. We have extensive documentation to help you develop your own completely custom template with the power of modern HTML and Handlebars helpers. Check out our theme documentation for more.

If you need a good starting point to make changes, you can copy the code in the existing post.hbs template and begin editing from there. Take a look at the post template code for Casper, the default theme for Ghost.

Accessing your custom template

Once you've finished your custom template you can upload it to your site and try the template out. Zip up the root folder of the theme and navigate back to the Design view within the Ghost admin. Use the 'Upload a theme' theme button to upload your zipped up theme, and make sure to activate it.

Post Template dropdown select in post settings

The final part of this process is to select and use the custom template you've just created. Create a new post, or navigate to an existing post and open the post settings panel using the cog icon in the top right of the screen. At the bottom of the panel you'll now see a dropdown select with the title of 'Template'. Use the dropdown to select your custom template, close the panel and update your post. You'll then be able to view the post with your new template applied.

Summary

Nice! You've successfully created a custom post template in your Ghost theme and it's now ready to use from within the editor. The custom template creation process can be repeated as many times as you like, allowing you to be more creative with art directed content and article layout variations.