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    

Templates

Explanation of the .hbs templates which make up a Ghost theme

Ghost requires that your theme have at least an index.hbs and a post.hbs template, all other templates are optional.

post.hbs is the default template for all single posts/pages, and index.hbs is the default template for all lists of posts.

It is highly recommended that you use a default.hbs file as a base layout for your theme, in order to be consistent with other themes. If you have significantly different layouts for different pages, you can have multiple layouts, build a hierarchy or use partials to encapsulate common parts of your theme.

The following templates names will be used to render the different views / pages available on a Ghost blog:

default.hbs

This is the default layout, or base template which contains all the boring bits of HTML that have to appear on every page – the <html>, <head> and <body> tags along with the {{ghost_head}} and {{ghost_foot}} helpers, as well as any HTML which makes up a repeated header and footer for the blog.

The default template contains the handlebars expression {{{body}}} to denote where the content from templates which extend the default template goes.

Page templates then have {{!< default}} as the very first line to specify that they extend the default template, and that their content should be placed into the place in default.hbs where {{{body}}} is defined.

index.hbs

This is the standard template for a list of posts. It is used by default for the home page and subsequent pages of blog posts. If your theme doesn't have a tag.hbs or author.hbs, the index.hbs template will be used instead to output those post lists as well.

The index.hbs template usually extends default.hbs. It gets passed a list of posts which are displayed using the {{#foreach}} helper.

See the index documentation for more information.

home.hbs

You can optionally provide a special template for the homepage. This template will only be used to render /, and not the subsequent pages like /page/2/.

See the home context documentation for more information.

post.hbs

This is the template for a single post, which also extends default.hbs.

In Casper (the current default theme), the single post template has it's own header, also using @blog global settings and then uses the {{#post}} data accessor to output all of the post details.

If you want to have a custom template for a specific post you can do so by creating a template with the name post-{{slug}}.hbs. For example if you have a post called 'My First Post' that lives at /my-first-post/ then you can add a template called post-my-first-post.hbs and this template will be used to render only this particular post.

See the post context documentation for more information.

page.hbs

You can optionally provide a page template for static pages. If your theme doesn't have a page.hbs template, Ghost will use the standard post.hbs template for pages.

Pages have exactly the same data available as a post, they simply don't appear in the list of posts.

If you want to have a custom template for a specific page you can do so by creating a template with the name page-{{slug}}.hbs. For example if you have a page called 'About' that lives at /about/ then you can add a template called page-about.hbs and this template will be used to render only the about page.

See the page context documentation for more information.

tag.hbs

You can optionally provide a tag template for the tag archive pages. If your theme doesn't have a tag.hbs template, Ghost will use the standard index.hbs template for tag pages.

Tag pages get access to both a list of posts (and pagination info) and details of the tag as top level objects. As in index.hbs, {{#foreach posts}}{{/foreach}} works to output the posts. You can get to the details of the tag using either path expression like {{tag.name}} or by using a block expression and entering the tag scope: {{#tag}}{{name}}{{/tag}}.

See the tag context documentation for more information.

If you want to have a custom template for a specific tag you can do so by creating a template with the name tag-{{slug}}.hbs. For example if you have a tag name 'Music' that lives at /tag/music/ then you can add a template called tag-music.hbs and this template will be used to render only the 'music' tag archive.

author.hbs

You can optionally provide an author template for the author archive pages. If your theme doesn't have an author.hbs template, Ghost will use the standard index.hbs template for author pages.

Author pages get access to both a list of posts and details of the author as top level objects. As in index.hbs, {{#foreach posts}}{{/foreach}} works to output the posts. You can get to the details of the author using either path expression like {{author.name}} or by using a block expression and entering the author scope: {{#author}}{{name}}{{/author}}.

See the author context documentation for more information.

If you want to have a custom template for a specific author you can do so by creating a template with the name author-{{slug}}.hbs, exactly the same as you can do for tags.

private.hbs

You can optionally provide a private template for the password form page which appears in password protected blogs. This is a highly specialised page which displays a form and an error.

See the private context documentation for more information.

subscribe.hbs

Documentation in progress ✨

error.hbs

You can optionally provide an error template for any 404 or 500 errors. If your theme doesn't provide an error.hbs Ghost will use its default.

To see how to access the data about an error, take a look at Ghost's default error template which is located in /core/server/views/error.hbs. Note, than the only helper you can use in this template is the {{asset}} helper.

amp.hbs

You can also provide an optionally template for AMP (Accelerated Mobile Pages). If your theme doesn't provide an amp.hbs file, Ghost will use its default.

You'll find the documentation for AMP support in themes on the AMP features page.

package.json

Please check out the package.json section to see the requirements and recommendations for your package.json file.

robots.txt

Themes can include a robots.txt, which will override the default robots.txt provided by Ghost.

Post styling & previewing

When building themes for Ghost please consider the scope of your classes, and in particular your IDs, to try to avoid clashes between your main styling and your post styling. You never know when a class name or in particular an ID (because of the auto-generation of IDs for headings) will get used inside a post. Therefore it's best to always scope things to a particular part of the page. E.g. #my-id could match things you don't expect whereas #themename-my-id would be safer.

Templates

Explanation of the .hbs templates which make up a Ghost theme