{"category":{"version":"58810495d172b61b00d73859","project":"542fe92a5eceb608003fddc8","_id":"58810495d172b61b00d7385a","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-04T12:33:46.255Z","from_sync":false,"order":0,"slug":"documentation","title":"Documentation"},"parentDoc":null,"project":"542fe92a5eceb608003fddc8","user":"542c5cfcddd3190e00228849","version":{"__v":1,"_id":"58810495d172b61b00d73859","project":"542fe92a5eceb608003fddc8","createdAt":"2017-01-19T18:25:25.206Z","releaseDate":"2017-01-19T18:25:25.206Z","categories":["58810495d172b61b00d7385a","58810495d172b61b00d7385b","58810495d172b61b00d7385c","58810495d172b61b00d7385d","58810495d172b61b00d7385e","58810495d172b61b00d7385f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.11.4","version":"0.11.4"},"_id":"58810495d172b61b00d73897","__v":0,"updates":["5577145ae6063e0d00481318"],"next":{"pages":[],"description":""},"createdAt":"2015-05-13T19:20:07.265Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"Ghost requires that your theme have at least an `index.hbs` and a `post.hbs` template, all other templates are optional.\n\n`post.hbs` is the default template for all single posts/pages, and `index.hbs` is the default template for all lists of posts. \n\nIt is **highly** recommended that you use a [`default.hbs`](#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.\n\nThe following templates names will be used to render the different views / pages available on a Ghost blog:\n\n* [index.hbs](#section-index-hbs)\n* [home.hbs](#section-home-hbs)\n* [post.hbs](#section-post-hbs), [post-{{slug}}.hbs](#section-post-hbs)\n* [page.hbs](#section-page-hbs), [page-{{slug}}.hbs](#section-page-hbs)\n* [tag.hbs](#section-tag-hbs), [tag-{{slug}}.hbs](#section-tag-hbs)\n* [author.hbs](#section-author-hbs), [author-{{slug}}.hbs](#section-author-hbs)\n* [private.hbs](#section-private-hbs)\n* [subscribe.hbs](#section-subscribe-hbs) (Beta)\n* [error.hbs](#section-error-hbs)\n* [amp.hbs](#section-amp-hbs)\n\n## default.hbs\n\nThis 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.\n\nThe default template contains the handlebars expression `{{{body}}}` to denote where the content from templates which extend the default template goes.\n\nPage 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.\n\n## index.hbs\n\nThis 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. \n\nThe `index.hbs` template usually extends `default.hbs`. It gets passed a list of posts which are displayed using the `{{#foreach}}` helper.\n\nSee the [index](doc:index-context) documentation for more information.\n\n## home.hbs\n\nYou 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/`.\n\nSee the [home context](doc:home-context) documentation for more information.\n\n## post.hbs\n\nThis is the template for a single post, which also extends `default.hbs`.\n\nIn Casper (the current default theme), the single post template has it's own header, also using `:::at:::blog` global settings and then uses the `{{#post}}` data accessor to output all of the post details.\n\nIf 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.\n\nSee the [post context](doc:post-context) documentation for more information. \n\n## page.hbs\n\nYou 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.\n\nPages have exactly the same data available as a post, they simply don't appear in the list of posts.\n\nIf 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.\n\nSee the [page context](doc:page-context) documentation for more information. \n\n## tag.hbs\n\nYou 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.\n\nTag 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}}`.\n\nSee the [tag context](doc:tag-context) documentation for more information.\n\nIf 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.\n\n## author.hbs\n\nYou 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.\n\nAuthor 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}}`. \n\nSee the [author context](doc:author-context) documentation for more information.\n\nIf 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.\n\n## private.hbs\n\nYou 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.\n\nSee the [private context](doc:private-context) documentation for more information.\n\n## subscribe.hbs\n\nDocumentation in progress ✨\n\n## error.hbs\n\nYou 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.\n\nTo 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/user-error.hbs`\n\n## amp.hbs\n\nYou can also provide an optionally template for AMP ([Accelerated Mobile Pages](https://www.ampproject.org/docs/get_started/about-amp.html)). If your theme doesn't provide an `amp.hbs` file, Ghost will use its default.\n\nYou'll find the documentation for AMP support in themes on the [AMP features](doc:amp) page.\n\n## package.json\n\nPackage.json is a format borrowed from [npm](https://www.npmjs.org/doc/json.html). Ghost currently looks for a `name` and `version` field.\nWe highly recommend adding an `author` and `description` field. The fields that Ghost requires will change as Ghost evolves, but for now the following is enough to make Ghost happy:\n\n```\n{\n  \"name\": \"mytheme\",\n  \"version\": \"0.1.0\"\n}\n```\n\n## robots.txt\n\nThemes can include a robots.txt, which will override the default robots.txt provided by Ghost.\n\n### Post styling & previewing\n\nWhen 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.","excerpt":"Explanation of the .hbs templates which make up a Ghost theme","slug":"templates","type":"basic","title":"Templates"}

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`](#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: * [index.hbs](#section-index-hbs) * [home.hbs](#section-home-hbs) * [post.hbs](#section-post-hbs), [post-{{slug}}.hbs](#section-post-hbs) * [page.hbs](#section-page-hbs), [page-{{slug}}.hbs](#section-page-hbs) * [tag.hbs](#section-tag-hbs), [tag-{{slug}}.hbs](#section-tag-hbs) * [author.hbs](#section-author-hbs), [author-{{slug}}.hbs](#section-author-hbs) * [private.hbs](#section-private-hbs) * [subscribe.hbs](#section-subscribe-hbs) (Beta) * [error.hbs](#section-error-hbs) * [amp.hbs](#section-amp-hbs) ## 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](doc:index-context) 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](doc: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 [email protected]` 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](doc: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](doc: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](doc: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](doc: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](doc: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/user-error.hbs` ## amp.hbs You can also provide an optionally template for AMP ([Accelerated Mobile Pages](https://www.ampproject.org/docs/get_started/about-amp.html)). 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](doc:amp) page. ## package.json Package.json is a format borrowed from [npm](https://www.npmjs.org/doc/json.html). Ghost currently looks for a `name` and `version` field. We highly recommend adding an `author` and `description` field. The fields that Ghost requires will change as Ghost evolves, but for now the following is enough to make Ghost happy: ``` { "name": "mytheme", "version": "0.1.0" } ``` ## 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.