Ghost Theme Structure


Ghost keeps a very basic theme structure with the files that contain the html elements at the root of the folder, and then all assets (css, js, images, etc) inside the assets folder. All of the files with html are actually .hbs files because handlebars will be processing those files and presenting the code on the front end.

So, lets take a look at the file structure inside the Casper theme folder and break down what the role of each file and folder is:

Theme Structure

Assets Folder

The assets folder is where all of your extra scripts, images, css, etc lives. If you want to add some extra functionality, usually this is where you will put the javascript files. These files are able to be accessed using the handlebars asset function (this will be covered in the next section).

default.hbs

default.hbs is the frame of every page of your Ghost blog. Stuff like Google analytics, menus, footers, stylesheets, favicon, or anything else you want to be a part of every page on your blog should be placed in this file.

index.hbs

The index.hbs is the code for your home page and subsequent pages when any sort of pagination is clicked on. Anything you change in here will change what your home page will look like, but it will not affect your post or static pages.

License

This is just the license provided by Ghost.

package.json

package.json is where you change the name and version of your theme. Ghost grabs this data and populates it into your Ghost settings so it knows the name of your theme. In the future, this will be expanded to need more options like the author's name, description, and compatibility.

Partials Folder

The partials folder is where you can create snippets of code that you want to be used multiple places. For example, Casper uses its loop.hbs file inside the partials folder to loop through all the posts and display some information. This is something they use in three different places, so rather than having the same code that has to be updated in three places, you can have a partial that you include and then only have to edit once

page.hbs

The page.hbs is the code for your static pages. You can change the way all of your static pages look inside of this file.

post.hbs

The post.hbs is how you change the way all of your posts look. This is where you go to style each of your post pages.

README.rtf

The README.rtf is usually just instructions provided by the theme author giving you information about the theme itself

tag.hbs

This is where you change what your tag pages look like. If this file does not exist, the tag pages will be styled based on the index.hbs, but if you want them to look different, this is where you can make changes.

Not Included in Casper

Some other structure options are available that are not used in the Casper theme but can be extremely useful.

home.hbs

This file changes just the look of the home page. The difference between this file and index.hbs is that index.hbs will use the same page on any pagination for older or newer posts. This file changes only the home page. This allows you to have a home page that then when someone clicks on older posts, takes them to a different looking page.

page-{slug}.hbs

This allows you to have specific html for a specific page. So, say you want your About Us page to look differently than your Contact Us page, you could create a page-about-us.hbs and a page-contact-us.hbs file that allow each of those pages to have their own specific html. The {slug} has to match the page url, so if your url is 'blog.com/about' then the file has to be page-about.hbs.

tag-{slug}.hbs

The tag-{slug}.hbs is the same as the page-{slug}.hbs above except for tag pages. So, if you have a specific tag that you want the page to be different from the other tags, then you can create its own custom .hbs file. Again, like above, the {slug} needs to match the tag name exactly.