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    

Structure

Overview of Ghost theme structure

The recommended file structure is:

.
├── /assets
|   └── /css
|       ├── screen.css
|   ├── /fonts
|   ├── /images
|   ├── /js
├── default.hbs 
├── index.hbs [required]
└── post.hbs [required]
└── package.json [required]

For the time being there is no requirement that default.hbs or any folders exist.

If you use assets, it is required that you keep them inside of an assets folder, and make use of the {{asset}} helper for serving css, js, image, font and other asset files. Without this, your theme may suffer from caching issues when updated.

It is also required that you make use of the {{ghost_head}} and {{ghost_foot}} helpers.

index.hbsand post.hbs are required – Ghost will not work if these two templates are not present.

Note on file changes

While edits to existing handlebars, js and css files are handled & updated on the fly when in development mode, you will need to restart Ghost each time you add or remove a file from the theme directory for it to be recognised and used.

Partials

You can also optionally add a /partials directory to your theme. This should include any part templates you want to use across your blog, for example list-post.hbs might include your template for outputting a single post in a list, which might then be used on the homepage, author & tag pages. To output the list-post.hbs example you would use {{> list-post}}.

.
├── /assets
    ├── /css
        ├── screen.css
    ├── /fonts
    ├── /images
    ├── /js
├── /partials
    ├── list-post.hbs
├── default.hbs
├── index.hbs [required]
└── post.hbs [required]
└── package.json [required]

The /partials directory is also where you can put templates to override the built-in templates used by certain helpers like pagination & navigation. Including a pagination.hbs file inside partials will let you specify your own HTML for pagination, and likewise with navigation.hbs. Note that these partials must be included using their helpers {{pagination}} and {{navigation}} and not using the partial syntax.

Layouts

Using a default.hbs file as a default layout for all templates is highly recommended. You can extend the default.hbs file in any other file using the layout syntax: {{!< default}}. It is possible to specify multiple layouts, and also to nest layouts.

Templates


Although partials can be custom with names of your choice, the templates used in a Ghost theme must follow strict naming conventions. Each template is used to render a specific page or section of a blog (called a Context, and each template gets given access to specific data. See the page on Templates for more information about the templates, or use this quick-list to reference the template you'd like more information about:

Helpers


Ghost templates are constructed from HTML and Handlebars. For an overview of how the Handlebars templating language works, please see the Handlebars section. The Helper Reference covers all of the native and custom Handlebars helpers available in Ghost and how to use them.

Contexts


Each page in a Ghost theme belongs to a context. The context can be determined by the URL, and tells you which template will be used, what data will be available and what will be output by the {{body_class}} helper. Below is a quick list of all context. For more details see the context table, in the Context Reference.

Structure

Overview of Ghost theme structure