{"_id":"5937b2388e8d9b002f1df277","category":{"_id":"5937b2388e8d9b002f1df26f","version":"5937b2378e8d9b002f1df26e","project":"542fe92a5eceb608003fddc8","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-04T12:33:46.255Z","from_sync":false,"order":0,"slug":"documentation","title":"Documentation"},"user":"542c5cfcddd3190e00228849","parentDoc":null,"project":"542fe92a5eceb608003fddc8","version":{"_id":"5937b2378e8d9b002f1df26e","project":"542fe92a5eceb608003fddc8","__v":1,"createdAt":"2017-06-07T07:58:47.936Z","releaseDate":"2017-06-07T07:58:47.936Z","categories":["5937b2388e8d9b002f1df26f","5937b2388e8d9b002f1df270","5937b2388e8d9b002f1df271","5937b2388e8d9b002f1df272","5937b2388e8d9b002f1df273","5937b2388e8d9b002f1df274"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0.0"},"__v":0,"updates":["54f5b2f8a217d62f008fae84","55584ac93a4ffb0d0053350d","55ca3582241e790d004f4737"],"next":{"pages":[],"description":""},"createdAt":"2014-10-04T15:49:39.432Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":2,"body":"[Handlebars](http://handlebarsjs.com/) is the templating language used by Ghost.\n\n> Handlebars provides the power necessary to let you build semantic templates effectively with no frustration.\n\nIf you're looking to get started writing your own theme, you'll probably want to get yourself familiar with handlebars syntax first. Have a read of the [handlebars documentation](http://handlebarsjs.com/expressions.html), or checkout this [tutorial from Treehouse](http://blog.teamtreehouse.com/getting-started-with-handlebars-js) – you can skip the first section on installation and usage (we’ve done that bit for you) and get stuck in with ‘Basic Expressions’.\n\nGhost also makes use of an additional library called `express-hbs` which adds some [additional features](https://github.com/barc/express-hbs#syntax) to handlebars which Ghost makes heavy use of, such as [layouts](structure#default-layout) and [partials](structure#partials).\n\n## Introduction to Handlebars\n\nThe key thing to keep in mind when wiring up your Ghost theme to output data, is that you can only output the data that you have available to you. Each template you build for a Ghost theme has specific pieces of data, depending on what the template is for (we refer to the purpose of a template as its 'context') - for example, `post.hbs` only has access to a single post, where as `index.hbs` will get a list of many posts.  You can find out what data a template has access to by looking it up in the [Context Table](/docs/context-overview#context-table).\n\nAll the data which a template has access to is effectively a big JSON object - a set of nested properties and their values, which looks something like this for a post (full details of the data structures can be found in the 'Data' section of the docs):\n\n```\n{\n  post: {\n    title: 'My blog post title',\n\tauthor: {\n      name: 'Jo Bloggs',\n      ...\n    },\n    ...\n  }\n}   \n``` \n\nHandlebars gives you the ability to access and output this data in different ways, through various Handlebars expressions.... \n\n## Handlebars Expressions\n\nAll of handlebars comprises expressions which are wrapped in curly braces, for example {{title}}. There are lots of variations of these expressions, and different ways they can be used. The rest of this page gives a rundown of the different types of expression. For details of helpers available in Ghost, please see the [Helper Reference](doc:helpers).\n\n### Data Expressions\n\nE.g. `{{title}}`, `{{name}}`\n\nThe most simple thing that Handlebars can do is output a piece of data that your template has access to. If you want to output the title for a blog post, and you know that posts have a data property called `title` which contains the title, then in your theme you can use the expression `{{title}}` to output the post title. \n\nData expressions are how you output a variable or property directly using Handlebars.\n\n#### HTML Data Expressions\n\nE.g. `{{{bio}}}`\n\nSometimes, the data you want to output might contain HTML, E.g. the Author's bio field. By default, Handlebars will output HTML as if it is plain text. However you can tell Handlebars to render HTML properly by using triple-braces around your data property, for example `{{{bio}}}`.\n\n#### Global Data\n\nE.g. `{{:::at:::blog.title}}`\n\nGhost also provides access to some global data through the [[email protected]}}`](doc:@blog) property, for example [email protected]}}`. **Note:** The `@` sign is also used to provide special properties inside of block helpers. \n\n### Path Expressions\n\nE.g `{{author.name}}`\n\nSometimes, the property you want to output isn't available in the current scope directly because it belongs to another object. For example if you want to output the name of the author of your post, then `{{name}}` won't work on its own. Instead you can use dot notation to access data via a path. For example the author's name would be: `{{author.name}}`. \n\nHandlebars allows you to do lots of different things using paths, including using `../` to traverse up the JSON object, and array indexing using syntax like `.[0]`,  check out the [Handlebars documentation](http://handlebarsjs.com/#paths) for more details.\n\n### Block Expressions (Scopes)\n\nE.g. `{{#post}}{{/post}}`\n\nSometimes, you want to output a lot more than just one property from an object. For example if you're creating a nicely styled author block for a post, you'll want to access lots of author properties. Rather than using lots of path expressions, instead you can use a block expression to open up a particular object and access its properties directly. This is referred to as **opening a 'scope'**. The scope you are in is very important for knowing what data is accessible.\n\nBlock expressions have an opening and a closing tag, much like HTML: `{{#author}}{{/author}}`. Between these opening and closing tags, we are in the 'author' scope, so we can access the properties of the author directly. For example:\n\n```\n{{#author}}\n\tMy name is {{name}}, visit my <a href=\"{{website}}\">Website!</a>\n{{/author}}\n```\n\nThe most common example of a block expression in Ghost is the post block expression used in `post.hbs`. Usually the whole template is wrapped with `{{#post}}{{/post}}` so that the rest of the template has direct access to post properties. We highly recommend using block expressions rather than path expressions wherever possible as this makes it easier to use the custom helpers provided by Ghost.\n\nAll block expressions support having an `{{else}}` block which is executed if the block expression doesn't meet certain criteria, for example if there is no post when attempting to open a `{{#post}}` scope, or if the tests an `{{#if}}` or `{{#has}}` helper are performing fail. It's even possible to use `{{else}}` with `{{#foreach}}`, which will be called if there are no items to loop over.\n\nAs well as using else, it is also possible to swap the `#` in a block helper for a `^`, which will negate the operation being performed. This essentially switches the opening block and the else block around. `{{^if}}` is the same as `{{#unless}}` and `{{^foreach posts}}{{/foreach}}` would output the template between the tags only if there were no posts to loop over.\n\n#### Block + Path Expressions\n\nA more advanced use of block expressions would be to use a path expression to target a specific post from within the `posts` helper. The following example shows how to work with latest post on the homepage:\n\n```\n{{#posts.[0]}}\n  <h3 class=\"first_title\">{{title}}</h3>\n  <div class=\"first_content\">{{content}}</div>\n{{/posts.[0]}}\n```\n\n### Helpers \n\nE.g. `{{content}}`, `{{url}}`\n\nThe difference between helpers, and all the other expressions we've seen so far is that helpers do some work behind the scenes, rather than just outputting data. Essentially, data expressions are variables, and helpers are functions. Ghost provides a set of helpers specifically designed to make building blog themes easy. Some of the helpers are general purpose and can be used in lots of places, but many of them have a very specific job to do.\n\nOne of the most important specific helpers is the `{{content}}` helper. It helps output the HTML content of a post and therefore only works when inside the post scope. The `{{content}}` helper has attributes that you can specify to restrict how much content is output, E.g. `{{content words=\"50\"}}`. Handlebars attributes are very similar to HTML attributes.\n\nOther helpers will do different things depending on where you use them - for example the `{{url}}` helper will work for posts, tags and authors, and will output the correct URL for the current object. `{{body_class}}` will output different classes depending on the context, for example it outputs `home-template` on the homepage and `post-template` on a post page.\n\nDate is a formatting helper. It takes a parameter as well as attributes, for example `{{date published_at format=\"MMMM DD, YYYY\"}}`, where `published_at` is the date you want to output, and the format attribute decides how to format the date. If you don't pass in a parameter, the `{{date}}` helper will use the `published_at` property by default if it is accessible.\n\nThe [Helper Reference](/docs/helpers#helper-listings) has a full list of all the helpers available in Ghost, explains what they do, what attributes they have and where they can be used.\n\n### Block Helpers\n\nE.g. `{{#if}}{{/if}}`, `{{#foreach posts}}{{/foreach}}`\n\nBlock helpers are very similar to block expressions. They are helpers which have a start and end tag, so they let you wrap blocks of your template. Handlebars has a number of built in block helpers, including the [`if` helper](http://handlebarsjs.com/block_helpers.html#conditionals), which lets you wrap a template block in a conditional. For example: `{{#if featured}}{{/if}}` lets you check if a post is featured.\n\nGhost has a number of additional block helpers, including `{{#foreach}}` which lets you iterate over a list of objects. This is particularly important on the `index.hbs` and other list templates as it allows you to loop through the posts with `{{#foreach posts}}{{/foreach}}`and output information about each one. Note the difference between the block helper `{{#foreach posts}}{{/foreach}}` and the block expression `{{#post}}{{/post}}`. The first allows you to output multiple posts, whereas the second just helps you access direct properties on one post.\n\nSome block helpers provide access to special properties, for example inside the `{{#foreach}}{{/foreach}}` helper you can access the [email protected]}}` property.\n\nThe [Helper Reference](/docs/helpers#helper-listings) has a full list of all the block helpers available in Ghost, explains what they do, what attributes they have and where they can be used.\n\n### Layout Expressions\n\nE.g. `{{!< default}}`, `{{{body}}}`\n\nLayouts let you define a base template which other templates can **extend**. The common usage of this in Ghost is to create a `default.hbs` layout which contains the header and footer HTML for your blog and has the `{{{body}}}` helper where the rest of the content should go.  Every other template then starts with the expression `{{!< default}}` to declare that it extends the default layout. You can define multiple layouts in your Ghost theme.\n\nMore information about the default layout can be found in the [layouts](structure#default-layout) section of the [structure](doc:structure) guide.\n\n**Note:** The layouts feature comes from [express-hbs](https://github.com/barc/express-hbs#syntax) and is not part of the normal Handlebars language.\n\n### Partial Expressions\n\nE.g. `{{> loop}}`\n\nPartials allow you to create small **reusable** templates which you include in other template files. For example, you might create a `loop.hbs` partial which you use on all of the listing templates to output a short post excerpt. Partials have to live in the `/partials/` directory, and are output with the `{{> loop}}` partial helper. The partial helper will also take a string path if you have subdirectories inside your partials directory, e.g. `{{> \"author/mini-bio\"}}`.\n\nMore information about partials can be found in the [partials](structure#partials) section of the [structure](doc:structure) guide.\n\n### Comments\n\nE.g. `{{!-- comments --}}`\n\nHandlebars also supports `{{!-- comments --}}`, which unlike HTML comments, won't be output in your page source, making them super useful. Handlebars comments can be multi-line the same as HTML comments","excerpt":"","slug":"handlebars","type":"basic","title":"Handlebars"}
[Handlebars](http://handlebarsjs.com/) is the templating language used by Ghost. > Handlebars provides the power necessary to let you build semantic templates effectively with no frustration. If you're looking to get started writing your own theme, you'll probably want to get yourself familiar with handlebars syntax first. Have a read of the [handlebars documentation](http://handlebarsjs.com/expressions.html), or checkout this [tutorial from Treehouse](http://blog.teamtreehouse.com/getting-started-with-handlebars-js) – you can skip the first section on installation and usage (we’ve done that bit for you) and get stuck in with ‘Basic Expressions’. Ghost also makes use of an additional library called `express-hbs` which adds some [additional features](https://github.com/barc/express-hbs#syntax) to handlebars which Ghost makes heavy use of, such as [layouts](structure#default-layout) and [partials](structure#partials). ## Introduction to Handlebars The key thing to keep in mind when wiring up your Ghost theme to output data, is that you can only output the data that you have available to you. Each template you build for a Ghost theme has specific pieces of data, depending on what the template is for (we refer to the purpose of a template as its 'context') - for example, `post.hbs` only has access to a single post, where as `index.hbs` will get a list of many posts. You can find out what data a template has access to by looking it up in the [Context Table](/docs/context-overview#context-table). All the data which a template has access to is effectively a big JSON object - a set of nested properties and their values, which looks something like this for a post (full details of the data structures can be found in the 'Data' section of the docs): ``` { post: { title: 'My blog post title', author: { name: 'Jo Bloggs', ... }, ... } } ``` Handlebars gives you the ability to access and output this data in different ways, through various Handlebars expressions.... ## Handlebars Expressions All of handlebars comprises expressions which are wrapped in curly braces, for example {{title}}. There are lots of variations of these expressions, and different ways they can be used. The rest of this page gives a rundown of the different types of expression. For details of helpers available in Ghost, please see the [Helper Reference](doc:helpers). ### Data Expressions E.g. `{{title}}`, `{{name}}` The most simple thing that Handlebars can do is output a piece of data that your template has access to. If you want to output the title for a blog post, and you know that posts have a data property called `title` which contains the title, then in your theme you can use the expression `{{title}}` to output the post title. Data expressions are how you output a variable or property directly using Handlebars. #### HTML Data Expressions E.g. `{{{bio}}}` Sometimes, the data you want to output might contain HTML, E.g. the Author's bio field. By default, Handlebars will output HTML as if it is plain text. However you can tell Handlebars to render HTML properly by using triple-braces around your data property, for example `{{{bio}}}`. #### Global Data E.g. [email protected]}}` Ghost also provides access to some global data through the [[email protected]}}`](doc:@blog) property, for example [email protected]}}`. **Note:** The `@` sign is also used to provide special properties inside of block helpers. ### Path Expressions E.g `{{author.name}}` Sometimes, the property you want to output isn't available in the current scope directly because it belongs to another object. For example if you want to output the name of the author of your post, then `{{name}}` won't work on its own. Instead you can use dot notation to access data via a path. For example the author's name would be: `{{author.name}}`. Handlebars allows you to do lots of different things using paths, including using `../` to traverse up the JSON object, and array indexing using syntax like `.[0]`, check out the [Handlebars documentation](http://handlebarsjs.com/#paths) for more details. ### Block Expressions (Scopes) E.g. `{{#post}}{{/post}}` Sometimes, you want to output a lot more than just one property from an object. For example if you're creating a nicely styled author block for a post, you'll want to access lots of author properties. Rather than using lots of path expressions, instead you can use a block expression to open up a particular object and access its properties directly. This is referred to as **opening a 'scope'**. The scope you are in is very important for knowing what data is accessible. Block expressions have an opening and a closing tag, much like HTML: `{{#author}}{{/author}}`. Between these opening and closing tags, we are in the 'author' scope, so we can access the properties of the author directly. For example: ``` {{#author}} My name is {{name}}, visit my <a href="{{website}}">Website!</a> {{/author}} ``` The most common example of a block expression in Ghost is the post block expression used in `post.hbs`. Usually the whole template is wrapped with `{{#post}}{{/post}}` so that the rest of the template has direct access to post properties. We highly recommend using block expressions rather than path expressions wherever possible as this makes it easier to use the custom helpers provided by Ghost. All block expressions support having an `{{else}}` block which is executed if the block expression doesn't meet certain criteria, for example if there is no post when attempting to open a `{{#post}}` scope, or if the tests an `{{#if}}` or `{{#has}}` helper are performing fail. It's even possible to use `{{else}}` with `{{#foreach}}`, which will be called if there are no items to loop over. As well as using else, it is also possible to swap the `#` in a block helper for a `^`, which will negate the operation being performed. This essentially switches the opening block and the else block around. `{{^if}}` is the same as `{{#unless}}` and `{{^foreach posts}}{{/foreach}}` would output the template between the tags only if there were no posts to loop over. #### Block + Path Expressions A more advanced use of block expressions would be to use a path expression to target a specific post from within the `posts` helper. The following example shows how to work with latest post on the homepage: ``` {{#posts.[0]}} <h3 class="first_title">{{title}}</h3> <div class="first_content">{{content}}</div> {{/posts.[0]}} ``` ### Helpers E.g. `{{content}}`, `{{url}}` The difference between helpers, and all the other expressions we've seen so far is that helpers do some work behind the scenes, rather than just outputting data. Essentially, data expressions are variables, and helpers are functions. Ghost provides a set of helpers specifically designed to make building blog themes easy. Some of the helpers are general purpose and can be used in lots of places, but many of them have a very specific job to do. One of the most important specific helpers is the `{{content}}` helper. It helps output the HTML content of a post and therefore only works when inside the post scope. The `{{content}}` helper has attributes that you can specify to restrict how much content is output, E.g. `{{content words="50"}}`. Handlebars attributes are very similar to HTML attributes. Other helpers will do different things depending on where you use them - for example the `{{url}}` helper will work for posts, tags and authors, and will output the correct URL for the current object. `{{body_class}}` will output different classes depending on the context, for example it outputs `home-template` on the homepage and `post-template` on a post page. Date is a formatting helper. It takes a parameter as well as attributes, for example `{{date published_at format="MMMM DD, YYYY"}}`, where `published_at` is the date you want to output, and the format attribute decides how to format the date. If you don't pass in a parameter, the `{{date}}` helper will use the `published_at` property by default if it is accessible. The [Helper Reference](/docs/helpers#helper-listings) has a full list of all the helpers available in Ghost, explains what they do, what attributes they have and where they can be used. ### Block Helpers E.g. `{{#if}}{{/if}}`, `{{#foreach posts}}{{/foreach}}` Block helpers are very similar to block expressions. They are helpers which have a start and end tag, so they let you wrap blocks of your template. Handlebars has a number of built in block helpers, including the [`if` helper](http://handlebarsjs.com/block_helpers.html#conditionals), which lets you wrap a template block in a conditional. For example: `{{#if featured}}{{/if}}` lets you check if a post is featured. Ghost has a number of additional block helpers, including `{{#foreach}}` which lets you iterate over a list of objects. This is particularly important on the `index.hbs` and other list templates as it allows you to loop through the posts with `{{#foreach posts}}{{/foreach}}`and output information about each one. Note the difference between the block helper `{{#foreach posts}}{{/foreach}}` and the block expression `{{#post}}{{/post}}`. The first allows you to output multiple posts, whereas the second just helps you access direct properties on one post. Some block helpers provide access to special properties, for example inside the `{{#foreach}}{{/foreach}}` helper you can access the [email protected]}}` property. The [Helper Reference](/docs/helpers#helper-listings) has a full list of all the block helpers available in Ghost, explains what they do, what attributes they have and where they can be used. ### Layout Expressions E.g. `{{!< default}}`, `{{{body}}}` Layouts let you define a base template which other templates can **extend**. The common usage of this in Ghost is to create a `default.hbs` layout which contains the header and footer HTML for your blog and has the `{{{body}}}` helper where the rest of the content should go. Every other template then starts with the expression `{{!< default}}` to declare that it extends the default layout. You can define multiple layouts in your Ghost theme. More information about the default layout can be found in the [layouts](structure#default-layout) section of the [structure](doc:structure) guide. **Note:** The layouts feature comes from [express-hbs](https://github.com/barc/express-hbs#syntax) and is not part of the normal Handlebars language. ### Partial Expressions E.g. `{{> loop}}` Partials allow you to create small **reusable** templates which you include in other template files. For example, you might create a `loop.hbs` partial which you use on all of the listing templates to output a short post excerpt. Partials have to live in the `/partials/` directory, and are output with the `{{> loop}}` partial helper. The partial helper will also take a string path if you have subdirectories inside your partials directory, e.g. `{{> "author/mini-bio"}}`. More information about partials can be found in the [partials](structure#partials) section of the [structure](doc:structure) guide. ### Comments E.g. `{{!-- comments --}}` Handlebars also supports `{{!-- comments --}}`, which unlike HTML comments, won't be output in your page source, making them super useful. Handlebars comments can be multi-line the same as HTML comments