The Ghost theme layer has built-in functionality to work with custom templates and pass them directly to the admin client so that they can be readily used when creating content using the editor. This allows theme developers to create replicable styles for a publication that can be implemented by any author or team user with a couple of clicks ✅

Overview

Rather than using a bloated page builder that comes with style limitations and site speed implications, a Ghost theme allows you to apply styles in a sensible manner, using HTML and CSS.

Once the custom template is in place, it can be selected from the post settings menu in the editor.

This tutorial walks you through the process for setting up custom templates using Ghost handlebars themes.

If you want to build custom static pages for your publication, for example a home page or an about page, read this tutorial which shows you how to map routes to a template using the routes.yaml file.

Create a custom template

To create a custom template follow this filename format:

custom-{{template-name}}.hbs

Replace {{template-name}} with only alphanumeric characters and dashes. This will then be picked up as a custom template within Ghost. Ensure you pick a memorable name, since this part of the file name will be transformed and shown in the dropdown menu as 'Template Name'.

Using this naming format is the only thing required to ensure Ghost picks up your custom template, which can then be used in any post or page.

From here you can create an entirely custom handlebars template to suit your needs and edit your CSS files as required. For further information about building a Handlebars template from scratch, visit the Handlebars frontend SDK documentation.

Example

On the Ghost blog, we use a custom template called custom-full-width.hbs to render unique styling for special posts like this. Our template is called Full Width.

There are countless use cases for custom templates, which can totally restyle an entire post or page, or just to change a few small elements on the page.

Usually, custom post templates are used for one-off pieces of content. If you need a whole collection of content to be rendered with a specific template, use dynamic routing configuration instead.

Implement new templates and CSS

Once you have finished creating your new custom template file and made any necessary adjustments to your CSS, upload an updated version of your theme to Ghost.

Theme files should always be in the .zip format, and you can import your updated theme from the design settings menu in Ghost admin.

Now you can test your new custom template on production by creating a new draft post, and selecting the correct template from the dropdown menu in the post settings menu:

This menu will only appear when you have one or more custom templates uploaded in your theme!


Add content to your new post and preview it to see your new custom template and styling in action.

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. This same process can be repeated to create multiple custom styles for your posts and pages to suit your needs.