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    

Changelog

Keep up to date with the latest changes

The following document acts as a reference for developers who want to keep their theme up-to-date with the latest changes in the Ghost theme API. Since the original public release of 0.3.2 there have been a number of changes to the Ghost theme API and the way Ghost themes work, resulting in some new requirements and some deprecated features.

Got ideas?!

If you have bright ideas for improvements we could make to our theme API, or use cases that aren't quite working, please tell us about it! We have a special #themes channel in our Slack team and a wishlist.

Keeping up to date

The best way to keep up-to-date with the changes is to subscribe to the developer blog. All theme related blog posts are tagged with 'themes', so you can subscribe to an RSS feed of only theme related posts if you prefer.

GScan

Ghost 1.0.0 will validate your theme, you can run the same tests online at GScan. You can upload your theme here and get a summary of any errors, warnings or recommendations. This will allow you to validate the theme and make it work with Ghost 1.0.0.

Note

GScan is also the underlying validation method when you upload your theme or activate it in Ghost Admin. If your theme uses some of the deprecated features, which are classified as a fatal error, because the theme won't be working with Ghost 1.0.0, you won't be able to upload or activate it. See the warning box below to have an overview which features will prevent your theme from being uploaded.

Ghost 1.6.0

(15th Aug 2017)

Improved

  • The {{#has}} helper is now able to do more comparisons:
    - `number` and `index` matching inside of foreach loops, including "nth" support
    - `slug` and `id` matching inside of posts, authors, tags, etc
    
    See the has helper docs for full details. More changes coming soon!

Ghost 1.5.0

No theme-related changes.

Ghost 1.4.0

(2nd Aug 2017)

New

  • We have added a new feature to be able to set custom code injections per post.
  • So {{ghost_head}} and {{ghost_foot}} helpers output both the global and the per post code injection if available.

Ghost 1.3.0

(1st Aug 2017)

Improved

  • The {{excerpt}} helper will now default to outputting the posts new custom_excerpt property if there is one. If custom_excerpt is not set the behaviour is the same as before.
  • Posts now have a {{custom_excerpt}} property which contains the user-provided custom excerpt.

Ghost 1.2.0

(31st July 2017)

New

  • Posts now have a {{primary_tag}} dynamic property that can be used to access the first tag associated with any post.

Ghost 1.0.2

(27th July 2017)

New

  • Posts now have a {{comment_id}} dynamic property that must be used when creating a unique post identifier for Disqus.

Ghost 1.0.0

(23rd July 2017)

Strong requirements around package.json

  • name is required
  • version is required
  • author.email is required, author.url and author.name are optional
  • 'Posts per page' will no longer be a setting in Ghost Admin, but a recommended property for the package.json file of the theme: posts_per_page [is highly recommended]
    (/v1.0.0/docs/packagejson#section--config-posts_per_page-)
  • Further optional properties will be possible to use, see here

Theme config

  • {{@blog.posts_per_page}} as global data attribute will be replaced with {{@config.posts_per_page}}, which is now set in the theme's package.json, instead of in settings. See config.

Image properties & helper renamed

  • The {{image}} helper has been removed. Use {{img_url}} instead. See here
  • {{author.image}} -> replace with {{author.profile_image}}. See here
  • {{author.cover}} -> replace with {{author.cover_image}}. See here
    • {{post.image}} -> replace with {{post.feature_image}}. See here
    • {{@blog.cover}} -> replace with {{@blog.cover_image}}. See here
    • {{tag.image}} -> replace with {{tag.feature_image}}. See here

Deprecated features removed

  • The usage of {{meta_description}} in <head> will be deprecated. It's going to be included in the {{ghost_head}} helper.
  • Removal of deprecated {{pageUrl}} helper. Use {{page_url}} instead.
  • Removal of deprecated {{body_class}} classes. Use only classes listed in the Context Overview. Classes that are deprecated include:
    • .archive-template appearing on paginated pages, use .paged
    • .post-template and .page appearing on static pages, use .page-template
    • .page-template-{{slug}} appearing on static pages, use .page-{{slug}}
    • Also note, .page-{{slug}} used to only appear on pages with custom templates, in 1.0.0 they will be ever present, the same as .tag-{{slug}} or .author-{{slug}}.

Miscellaneous

  • All themes are validated by GScan, and can only be activated if they are valid.
  • Favicon is now an upload in settings, rather than a theme feature. Favicons included in themes will no longer work.
  • The {{get}} helper's {{else}} condition is now only triggered for errors, not empty results, instead please use {{else}} on the block helper you use inside the {{#get}} helper.

Theme upload and activation restrictions

The usage of the following deprecated helpers and object attributes will cause that the theme can't be uploaded or activated:

  • {{pageUrl}}
  • {{image}}
  • {{author.image}}
  • {{author.cover}}
  • {{post.image}}
  • {{post.author.image}}
  • {{post.author.cover}}
  • {{post.tags.[#].image}}
  • {{@blog.cover}}
  • {{tag.image}}

Theme activation and upload is also not possible if the following cases apply:

  • Usage of invalid Handlebars
  • Missing index.hbs template
  • Missing post.hbs template
  • Usage of Symlinks

Ghost 0.11.0 - Ghost 0.11.10

No theme-related changes

Ghost 0.11.0

(15th September 2016)

No changes

Ghost 0.10.0

(29th August 2016)

New

  • helpers {{amp_ghost_head}}, {{amp_content}} and {{amp_components} for AMP support
  • template amp.hbs

Ghost 0.9.0

(27th July 2016)

New

  • timezone property available via @blog
  • {{#foreach}} and {{tags}} respect the visibility property, meaning internal tags are not shown
  • if your theme contains a manifest.json in the root it is now served as a static file

Ghost 0.8.0

(18th May 2016)

New

  • @labs global property, currently has publicAPI and subscribers properties
  • twitter and facebook properties available via @blog
  • twitter and facebook properties available for authors / users
  • {{twitter_url}} and {{facebook_url}} helpers for outputting urls based on usernames
  • (labs only) subscribe context, with subscribe.hbs template & {{subscribe_form}} helper

Ghost 0.7.9

(7th April 2016)

Improved

  • page_url helper now supports "next" and "prev" as strings, rather than variables

Ghost 0.7.8

(18th February 2016)

No changes

Ghost 0.7.7

(18th February 2016)

No changes

Ghost 0.7.6

(3rd February 2016)

Fixed

  • current class in navigation now gets applied even if you missed a trailing slash from the URL.

Ghost 0.7.5

(12th Jan 2016)

New

  • from and to attribute for both {{foreach}} and {{tags}}

Ghost 0.7.4

(22nd Dec 2015)

Fixed

  • {{meta_title}}, {{meta_description}}, {{body_class}} & {{post_class}} no longer throw aSyNcId errors when used inside the {{#get}} helper, or the prev & next post helpers.
  • The @last variable will now be correct when using the limit attribute with {{#foreach}}
  • ghost.url.api JavaScript utility works correctly with multiple requests

Ghost 0.7.3

(16th Dec 2015)

New

  • permalinks and posts_per_page properties available via @blog
  • limit attribute for both {{foreach}} and {{tags}}
  • Custom post templates i.e. post-{{slug}}.hbs

Fixed

  • {{ghost_head}} overwriting author.image with author.cover
  • {{pagination}} now works inside the {{#get}} helper

Changed

  • ghost.url.api JavaScript utility can now be included on external sites

Note: in 0.7.3 the way Ghost handles pages of the RSS feed that don't exist has changed (they now correctly return 404). This has impacted on some themes which were parsing the RSS feed to provide features.

Ghost 0.7.2

(27th Nov 2015)

New

  • {{#get}} helper (Beta access only)
  • ghost.url.api JavaScript function (Beta access only)

Ghost 0.7.1

(27th Sep 2015)

Fixed

  • bug with {{#if current}} in {{navigation}} helper

Ghost 0.7.0

(3rd Sep 2015)

New

  • {{foreach}} now supports block params e.g. {{foreach posts as |mypost|}}
  • {{foreach}} has an a @number property that outputs the index, starting with 1 instead of 0.

Fixed

  • {{tags}} and {{author}} not working inside {{prev_post}} and {{next_post}}

Changed

  • {{tags}} now respects the order that tags are added to posts

Ghost 0.6.4

(21 May 2015)

Fixed

  • {{meta_description}} not working correctly on pages

Ghost 0.6.3

(14 May 2015)

New

  • New private context, with private.hbs template & .private-template body class
  • Custom author templates i.e. author-{{slug}}.hbs

Fixed

  • {{meta_title}} not working correctly on pages

Ghost 0.6.2

(22 Apr 2015)

Fixed

  • {{#prev_post}} & {{#next_post}} helpers not rendering

Ghost 0.6.1

(22 Apr 2015)

Fixed

  • {{ghost_head}} throwing errors on custom error.hbs pages
  • {{author.email}} being incorrectly available sometimes

Ghost 0.6.0

(13 Apr 2015)

New:

  • {{#prev_post}} & {{#next_post}} helper

Fixed

  • @blog globals now work in navigation.hbs and pagination.hbs
  • {{meta_title}} and {{meta_description}} now work inside of the post scope

Ghost 0.5.10

(9 Mar 2015)

No changes

Ghost 0.5.9

(28 Feb 2015)

New:

  • {{navigation}} helper
  • {{@blog.navigation}} data

Ghost 0.5.8

(12 Jan 2015)

Fixed

  • {{#has}} helper no longer matches partial tags
  • {{excerpt}} helper handles footnotes correctly

Changed

  • {{image}}, {{meta_title}} and {{meta_description}} updated for tags
  • {{url}} and {{image}} are now synchronous

Ghost 0.5.7

(15 Dec 2014)

No changes

Ghost 0.5.6

(4 Dec 2014)

Fixed

  • {{image}} helper works correctly with subdirectories

Ghost 0.5.5

(19 Nov 2014)

No changes

Ghost 0.5.4

(18 Nov 2014)

No changes

Ghost 0.5.3

(21 Oct 2014)

Changed

  • {{ghost_head}} output

Fixed

  • Themes now work correctly when symlinked

Ghost 0.5.2

(25 Sep 2014)

New:

  • {{#is}} helper
  • {{image}} for posts
  • Custom tag templates i.e. tag-{{slug}}.hbs

Changed

  • {{body_class}} output
  • {{meta_title}} output
  • {{meta_description}} output
  • {{ghost_head}} output

Deprecated

  • .archive-template and .page classes from {{body_class}}.
  • .post-template will soon only appear on posts, not pages.

Ghost 0.5.0

(11th Aug 2014)

New

  • Author pages i.e. author.hbs
  • home.hbs template
  • {{plural}} helper

Changed

  • {{has}} helper updates for authors
  • {{author}} changed to output HTML

Deprecated

  • {{author.email}} now outputs an empty string

Please see the multi-user blog post for more information.

Ghost 0.4.2

(26th Mar 2014)

New

  • package.json support (will be required)
  • {{log}} helper
  • {{#has}} helper
  • Tag pages tag.hbs
  • Custom page templates i.e. page-{{slug}}.hbs

Changed

  • {{pageUrl}} -> {{page_url}}
  • {{tags}} changed to output HTML

Deprecated

  • {{pageUrl}} will be removed

Please see the 0.4.2 blog post for more information.

Ghost 0.4.0

(13th Jan 2014)

New

  • Featured posts
  • Static pages with page.hbs
  • Custom error pages error.hbs
  • Customisable favicon
  • {{asset}} helper
  • {{encode}} helper

Changed

  • {{tags}} got prefix and suffix options
  • {{excerpt}} got unicode character support

Deprecated

  • Using {{@blog.url}} or relative urls for assets - please use the {{asset}} helper

Please see the 0.4.0 blog post for more information.

Changelog

Keep up to date with the latest changes