{"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":"58810495d172b61b00d73894","__v":0,"updates":["54374b6a3474fb0800a20ec6","5471242a07fc8f08008dc0d1","555bf71d696e4c3700bde838","571b901dd2ed1c17005a7a31"],"next":{"pages":[],"description":""},"createdAt":"2014-10-04T12:47:43.618Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":1,"body":"If you're someone looking to make a few customisations to an existing theme, you may find the help articles on [support.ghost.org](http://support.ghost.org/?s=theme) more useful, as they cover the most common adjustments like adding disqus or navigation step-by-step.\n\nIf you're looking to start building your own custom theme from scratch, or using another theme as a basis, then this guide is for you :)\n\n## Setting Up\n\nThe first thing you'll need to do is setup a local development environment for Ghost. Use whichever is your preferred method of installing Ghost (zip, git or npm) to get it running on your computer, the Ghost [README.md](https://github.com/TryGhost/Ghost) and [support site](http://support.ghost.org/installation) have more information about getting installed.\n\nThe most important thing is that you run Ghost in **development** mode **not** production mode (this means using `npm start` rather than `npm start --production`) because in **development** mode you don't have to keep restarting Ghost to see your changes.\n\nYou'll also need an editor which has good support for Handlebars. [Brackets](http://brackets.io) is a free editor which works well for editing theme files, alternatively IntelliJ, Sublime and many other popular IDEs have great Handlebars support either built in or via a plugin.\n\n## Creating Your Own Theme\n\nOnce you've got your development environment setup and running in **development** mode, it's time to decide whether you want to create a brand new theme from scratch, or whether you want to use another theme, such as [Casper](https://github.com/TryGhost/Casper) as a base. You may prefer to code up your new design in to HTML & CSS first, and then convert this into a working theme.\n\nWhichever method you choose, you need to make sure you have a folder in your `/content/themes/` directory with an appropriate name, ready to contain your theme files. At the bare minimum, the directory should contain an `index.hbs` file, a `post.hbs` file and a `package.json` file, which contains the name and version number of your theme.  See the section on [structure](doc:structure) for further details of the recommended and required parts of a theme's structure.\n\nOnce you've got your theme directory in place, you'll need to restart Ghost. Ghost won't detect new files automatically, but it will pick up changes to those files once it knows about them (providing you're in development mode). Navigate to `/ghost/settings/`, select your new theme from the dropdown and save the new settings to activate your theme.\n\nYou're now ready to start making changes. Remember to restart Ghost if you add a new `.hbs` file. Apart from this, you'll only need to refresh the page to see your changes.\n\n### Outputting posts\n\nYour theme must have at least an `index.hbs` and a `post.hbs` template. `index.hbs` is for outputting the main post list, and `post.hbs` is for outputting each individual post. You can add more template files to provide more structure and styling to various parts of your blog, or alternatively Ghost will always use `index.hbs` for lists and `post.hbs` for single posts.\n\nFor full details of how to output your posts, see the [post documentation](/docs/post).\n\n#### Post lists\n\n`index.hbs` gets access to a set of posts which can be output using the foreach helper, E.g.\n\n```\n{{#foreach posts}}\n// here we are in the post scope\n// whatever you put here gets run for each post \n{{/foreach}}\n```\n\nThe [{{#foreach}}](doc:foreach) helper has various options to help you output your posts, and for details of what can be output inside the foreach loop, see the [post documentation](/docs/post). \n\nWhen outputting a list of posts, you'll likely also need to use the [{{pagination}}](doc:pagination) helper so that you can navigate between pages of posts\n\n#### Individual posts\n\n`post.hbs` only ever gets access to a single post, which can be output using the post block expression, E.g.\n\n```\n{{#post}}\n// here we are in the post scope\n{{/post}}\n```\n\nThe [post documentation](/docs/post) contains details of what can be output once inside the post scope either in a list or individual post.\n\n#### Post author\n\nWhen inside the post scope, you can output details of the post's author using the `{{author}}` data expression. You can get access to sub-properties of the author using path expressions, for example  `{{author.name}}` to output the name of the author.\n\nYou can use `{{author}}` on it's own to output pre-formatted HTML of the author's name with a link to their author page.\n\nThis can also be done by using a block expression:\n\n```\n{{#author}}\n    <a href=\"{{url}}\">{{name}}</a>\n{{/author}}\n```\nSee the section on the [`{{author}}`](author) helper for more information on the author helper and the available sub properties.\n\n#### Post Tags\n\nWhen inside the post scope, you can also get access to the list of tags associated with the post. You can use `{{tags}}` to output a customisable list of tags, this can also be done by using a block expression:\n\n```\n<ul>\n    {{#foreach tags}}\n        <li>{{name}}</li>\n    {{/foreach}}\n</ul>\n```\n\nSee the section on the [`{{tags}}`](doc:tags) helper for details of the options.\n\n### Global Settings\n\nGhost themes have access to a number of global settings via the `:::at:::blog` global data accessor, E.g. [email protected]}}` to display your blog's title. See [@blog](blog) for more details.\n\n### Building your theme\n\nOnce you've created basic `index.hbs` and `post.hbs` templates for your theme, you can start to add customised templates for various aspects of your blog such as tag or author pages. Details of the various templates available can be found in the [Structure](doc:structure) documentation. The [handlebars](doc:handlebars) guide details how to use handlebars, and the documentation on the various [helpers](doc:helpers) explains all the options you have when outputting various bits of data.\n\n### Testing your theme\n\nIf you're looking for dummy or test content to help you test your theme, you'll find some handy links over on this [GitHub issue](https://github.com/TryGhost/Ghost/issues/1553).","excerpt":"This page will help you get up and running with Ghost Themes.","slug":"getting-started","type":"basic","title":"Getting Started"}

Getting Started

This page will help you get up and running with Ghost Themes.

If you're someone looking to make a few customisations to an existing theme, you may find the help articles on [support.ghost.org](http://support.ghost.org/?s=theme) more useful, as they cover the most common adjustments like adding disqus or navigation step-by-step. If you're looking to start building your own custom theme from scratch, or using another theme as a basis, then this guide is for you :) ## Setting Up The first thing you'll need to do is setup a local development environment for Ghost. Use whichever is your preferred method of installing Ghost (zip, git or npm) to get it running on your computer, the Ghost [README.md](https://github.com/TryGhost/Ghost) and [support site](http://support.ghost.org/installation) have more information about getting installed. The most important thing is that you run Ghost in **development** mode **not** production mode (this means using `npm start` rather than `npm start --production`) because in **development** mode you don't have to keep restarting Ghost to see your changes. You'll also need an editor which has good support for Handlebars. [Brackets](http://brackets.io) is a free editor which works well for editing theme files, alternatively IntelliJ, Sublime and many other popular IDEs have great Handlebars support either built in or via a plugin. ## Creating Your Own Theme Once you've got your development environment setup and running in **development** mode, it's time to decide whether you want to create a brand new theme from scratch, or whether you want to use another theme, such as [Casper](https://github.com/TryGhost/Casper) as a base. You may prefer to code up your new design in to HTML & CSS first, and then convert this into a working theme. Whichever method you choose, you need to make sure you have a folder in your `/content/themes/` directory with an appropriate name, ready to contain your theme files. At the bare minimum, the directory should contain an `index.hbs` file, a `post.hbs` file and a `package.json` file, which contains the name and version number of your theme. See the section on [structure](doc:structure) for further details of the recommended and required parts of a theme's structure. Once you've got your theme directory in place, you'll need to restart Ghost. Ghost won't detect new files automatically, but it will pick up changes to those files once it knows about them (providing you're in development mode). Navigate to `/ghost/settings/`, select your new theme from the dropdown and save the new settings to activate your theme. You're now ready to start making changes. Remember to restart Ghost if you add a new `.hbs` file. Apart from this, you'll only need to refresh the page to see your changes. ### Outputting posts Your theme must have at least an `index.hbs` and a `post.hbs` template. `index.hbs` is for outputting the main post list, and `post.hbs` is for outputting each individual post. You can add more template files to provide more structure and styling to various parts of your blog, or alternatively Ghost will always use `index.hbs` for lists and `post.hbs` for single posts. For full details of how to output your posts, see the [post documentation](/docs/post). #### Post lists `index.hbs` gets access to a set of posts which can be output using the foreach helper, E.g. ``` {{#foreach posts}} // here we are in the post scope // whatever you put here gets run for each post {{/foreach}} ``` The [{{#foreach}}](doc:foreach) helper has various options to help you output your posts, and for details of what can be output inside the foreach loop, see the [post documentation](/docs/post). When outputting a list of posts, you'll likely also need to use the [{{pagination}}](doc:pagination) helper so that you can navigate between pages of posts #### Individual posts `post.hbs` only ever gets access to a single post, which can be output using the post block expression, E.g. ``` {{#post}} // here we are in the post scope {{/post}} ``` The [post documentation](/docs/post) contains details of what can be output once inside the post scope either in a list or individual post. #### Post author When inside the post scope, you can output details of the post's author using the `{{author}}` data expression. You can get access to sub-properties of the author using path expressions, for example `{{author.name}}` to output the name of the author. You can use `{{author}}` on it's own to output pre-formatted HTML of the author's name with a link to their author page. This can also be done by using a block expression: ``` {{#author}} <a href="{{url}}">{{name}}</a> {{/author}} ``` See the section on the [`{{author}}`](author) helper for more information on the author helper and the available sub properties. #### Post Tags When inside the post scope, you can also get access to the list of tags associated with the post. You can use `{{tags}}` to output a customisable list of tags, this can also be done by using a block expression: ``` <ul> {{#foreach tags}} <li>{{name}}</li> {{/foreach}} </ul> ``` See the section on the [`{{tags}}`](doc:tags) helper for details of the options. ### Global Settings Ghost themes have access to a number of global settings via the [email protected]` global data accessor, E.g. [email protected]}}` to display your blog's title. See [@blog](blog) for more details. ### Building your theme Once you've created basic `index.hbs` and `post.hbs` templates for your theme, you can start to add customised templates for various aspects of your blog such as tag or author pages. Details of the various templates available can be found in the [Structure](doc:structure) documentation. The [handlebars](doc:handlebars) guide details how to use handlebars, and the documentation on the various [helpers](doc:helpers) explains all the options you have when outputting various bits of data. ### Testing your theme If you're looking for dummy or test content to help you test your theme, you'll find some handy links over on this [GitHub issue](https://github.com/TryGhost/Ghost/issues/1553).