The Ghost Themes Developer Hub

Welcome to the Ghost Themes developer hub. You'll find comprehensive guides and documentation to help you start working with Ghost Themes as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Getting Started

This page will help you get up and running with Ghost Themes.

If you're someone looking to make a few customisations to an existing theme, you may find the help articles on help.ghost.org more useful, as they cover the most common adjustments like adding disqus or navigation step-by-step.

If you're looking to start building your own custom theme from scratch, or using another theme as a basis, then this guide is for you :)

Setting Up

The first thing you'll need to do is setup a local development environment for Ghost. We highly recommend using the Ghost-CLI to set up a local Ghost installation (the further documentation will assume that you're using Ghost-CLI), but you can use whichever method you prefer to install Ghost (zip, git or npm) and to get it running on your computer.

The most important thing is that you run Ghost in development mode not production mode (this means using ghost start --development rather than ghost start) because in development mode caching is avoided to make your life easier. We also recommend using nodemon to restart Ghost automatically when new files are added.

You'll also need an editor which has good support for Handlebars. Brackets is a free editor which works well for editing theme files, alternatively IntelliJ, Sublime, Atom and many other popular IDEs have great Handlebars support either built in or via a plugin.

Creating Your Own Theme

Once you've got your development environment setup and running in development mode, it's time to decide whether you want to create a brand new theme from scratch, or whether you want to use another theme, such as Casper as a base. You may prefer to code up your new design in to HTML & CSS first, and then convert this into a working theme.

Whichever method you choose, first you need to get your theme to a the bare minimum, which will allow you to upload the theme via Ghost Admin:
The directory should contain

  • an index.hbs file,
  • a post.hbs file and
  • a package.json file,

which needs to contain e. g. the name and version number of your theme, more about the requirements for your package.json file can be found here. See the section on structure for further details of the recommended and required parts of a theme's structure.

Once you've got your basic theme directory in place, you'll need to start Ghost in development mode with ghost start --development and upload it. Navigate to "Design" in Ghost Admin and click on "Upload a theme". You should be able to activate it, when all GScan requirements are fulfilled.

You're now ready to start making changes. You can either directly edit files within your content/themes directory, or upload new versions via the Ghost Admin. Remember to restart Ghost if you add a new .hbs file and edit directly in your content/themes directory. Apart from this, you'll only need to refresh the page to see your changes.

Outputting posts

Your theme must have at least an index.hbs and a post.hbs template. index.hbs is for outputting the main post list, and post.hbs is for outputting each individual post. You can add more template files to provide more structure and styling to various parts of your blog, or alternatively Ghost will always use index.hbs for lists and post.hbs for single posts.

For full details of how to output your posts, see the post documentation.

Post lists

index.hbs gets access to a set of posts which can be output using the foreach helper, E.g.

{{#foreach posts}}
// here we are in the post scope
// whatever you put here gets run for each post 
{{/foreach}}

The {{#foreach}} helper has various options to help you output your posts, and for details of what can be output inside the foreach loop, see the post documentation.

When outputting a list of posts, you'll likely also need to use the {{pagination}} helper so that you can navigate between pages of posts

Individual posts

post.hbs only ever gets access to a single post, which can be output using the post block expression, E.g.

{{#post}}
// here we are in the post scope
{{/post}}

The post documentation contains details of what can be output once inside the post scope either in a list or individual post.

Post author

When inside the post scope, you can output details of the post's author using the {{author}} data expression. You can get access to sub-properties of the author using path expressions, for example {{author.name}} to output the name of the author.

You can use {{author}} on it's own to output pre-formatted HTML of the author's name with a link to their author page.

This can also be done by using a block expression:

{{#author}}
    <a href="{{url}}">{{name}}</a>
{{/author}}

See the section on the {{author}} helper for more information on the author helper and the available sub properties.

Post Tags

When inside the post scope, you can also get access to the list of tags associated with the post. You can use {{tags}} to output a customisable list of tags, this can also be done by using a block expression:

<ul>
    {{#foreach tags}}
        <li>{{name}}</li>
    {{/foreach}}
</ul>

See the section on the {{tags}} helper for details of the options.

Global Settings

Ghost themes have access to a number of global settings via the @blog global data accessor, E.g. {{@blog.title}} to display your blog's title. See @blog for more details.

Building your theme

Once you've created basic index.hbs and post.hbs templates for your theme, you can start to add customised templates for various aspects of your blog such as tag or author pages. Details of the various templates available can be found in the Structure documentation. The handlebars guide details how to use handlebars, and the documentation on the various helpers explains all the options you have when outputting various bits of data.

Testing your theme

If you're looking for dummy or test content to help you test your theme, you'll find some handy links over on this GitHub issue.

To see if your theme fits the Ghost 1.0 requirements, you can go over to GScan and upload and validate it.

Getting Started

This page will help you get up and running with Ghost Themes.