This is the second part of our Ghost theme design tutorial series. Everything from here assumes you have a foundational understanding of Ghost. If not, before continuing please take the time to read Understanding Ghost: Stages of Design).
As we discussed in the previous part, there are two stages to designing a theme for Ghost: Template File Creation and Styling.
In this tutorial we're going to focus on the first stage, by guiding you step-by-step through the process of setting up your theme's templates. You'll learn about Ghost's template file and partial system, its Handlebars template tags, and how to write your theme's markup skeleton.
Note: This tutorial is conducted on a Windows machine, so please take the equivalent steps on your preferred OS.
You will also need to have your preferred code editor handy; this tutorial will be carried out in Sublime Text 2.
Installing Ghost Locally
The first thing you'll need to do is install Ghost on your local machine. Doing so is quite easy, as long as you have the required prerequisites on your system. There's no need to run XAMPP or the equivalent in order to run Ghost on your local machine as it will actually run itself.
Note: Occasionally when you create a new theme, restart Ghost, and then select the new theme in admin, it may still load CSS from the previous theme. If you experience this issue while completing this tutorial series or anytime while creating a new theme all you need to do is perform a second restart of Ghost. An additional restart should clear the cache so the new theme's CSS becomes visible.
Once you have followed the instructions and installed Ghost on your local machine (and verified it's all working properly) you'll be ready to begin creating your Ghost theme starting with the steps below.
Begin a New Blank Theme
To get started we're going to create and activate a blank Ghost theme with the absolute minimum of required files.
Step 1:
In Windows Explorer (or equivalent) navigate to the folder into which you installed Ghost. You should see the following structure inside your main Ghost folder:
Step 2:
Navigate into the "content > themes" folder, where you will see the folder of the default theme "casper".
Step 3:
In this location, create a new folder and name it whatever you would like your theme to be called. In this tutorial we'll be creating a theme named "UberTheme" and so that is the name of the folder we'll create:
Add the Required Files
We're now going to add the required template files, without which you'll get errors if you try to activate your new theme.
The two files that are absolutely essential for a Ghost theme to run are:
index.hbs: controls display of your latest posts / homepage
post.hbs: controls display of single posts viewed individually
Step 1:
In your preferred code editor, create a new file then save it into your "UberTheme" folder as "index.hbs". You don't have any code to add to the file just yet so the file you create will be blank.
Step 2:
Create a second new file, then save that also into your "UberTheme" folder, this time as "post.hbs". Like the "index.hbs" file you created during the previous step, this file will also be empty/blank.
The inside of your "UberTheme" folder should now look like this:
Activate Tour Theme
We now need to start / restart Ghost in order to see "UberTheme" come up in the list of available themes in the admin panel so we can select and activate it.
Step 1:
If you already have Ghost running, shut it down by pressing CTRL+C in your terminal then, when prompted, type "y" followed by ENTER.
Step 2:
Start / restart Ghost by typing "npm start" in your terminal.
Tip: If you're not sure how to open the terminal so that you can perform the step above, navigate to your "Ghost" folder, press and hold SHIFT, right-click to bring up the Windows options menu, and then left-click on "Open Command window here".
Note: The steps above assume you have visited How to Install Ghost for instructions on installing and running Ghost.
Step 3:
Visit your Ghost admin panel, (signing in if required), typically located at http://localhost:2368/ghost
Step 4:
Click the "SETTINGS" button on the top menu in your admin panel:
This will take you to the "SETTINGS > General" section of your admin panel.
Step 5:
Scroll down to the bottom of the page, then locate and expand the "Theme" dropdown list. You should see "UberTheme" as one of the options:
Step 6:
Select "UberTheme" from the list, then click the blue "SAVE" button at the top right of the page.
Step 7:
In your browser, visit the front end of your Ghost installation, typically located at http://localhost:2368/
Result: You should see nothing but a blank white browser window.
If you don't see a blank white browser window and instead you see something like the image below, please go through the above steps again and make sure you have named your template files correctly:
Complete the File and Folder Structure
The only absolutely required files are the "index.hbs" and "post.hbs" template files as described in the last section.
However there are two more files you're going to want to use in pretty much any theme, even though they're not strictly required, so we'll add those now. We'll also organize a folder structure to hold any additional files added to your theme later on.
Theme Wrapper File
There's only one more main template file you're going to want in the root folder of your theme, and that's the "default.hbs" file.
This file creates the "wrapper" code for your theme, i.e. the head and foot code that will be wrapped around each page of a site running your theme. It will contain your standard <html>, <head> and <body> sections, as well as some template tags that will output important Ghost code.
We'll cover what actually has to be written into this file in more detail later. For now, let's just create the empty file itself.
Step 1:
In your preferred code editor, create a new file then save it into your "UberTheme" folder as "default.hbs".
Create Your Partials Folder
With Handlebars templating you have the ability to create what are called "partial" template files. These partial template files let you break your theme down into smaller components for a more modular, well organized structure.
For example, you might wish to split your layout into "header", "main" and "footer" sections, with the code for each contained in its own partial file. You'll see this process in practice later on. For now, we'll just create the folder that will be used to hold these "partial" files.
Step 1:
In Windows Explorer (or equivalent) navigate to your "UberTheme" folder.
Step 2:
Create a new folder and name it "partials".
Note: It is important to ensure this folder is named correctly and located in the theme's root folder, or Ghost will not be able to find your partial template files.
Assets Folder Structure
When we reach the styling stage, all of your styling related files will go into your "assets" folder, including CSS, JS, font and image files.
Note: You are not required to name the folder "assets" - you can actually name it anything you wish. We are simply following the best practices guidelines from Ghost in this tutorial.
Step 1:
In Windows Explorer (or equivalent) navigate to your "UberTheme" folder.
Step 2:
Create a new folder and name it "assets".
Step 3:
Navigate into your "assets" folder.
Step 4:
Create a new folder and name it "css".
Step 5:
Create a new folder and name it "fonts".
Step 6:
Create a new folder and name it "images".
Step 7:
Create a new folder and name it "js".
Your theme file and folder structure should now look like this:
Add your stylesheet file
Technically, adding your stylesheet file could be called part of the styling process. However, we are going to write the <head> section in the next stage of the tutorial, and as part of that we will want to link your theme's stylesheet and verify it is loading.
For that purpose, we will create a stylesheet file that will add a background color to your theme so we can subsequently ensure it's linked in your <head> section correctly.
Step 1:
In your preferred code editor, create a new file.
Step 2:
Add the following CSS to the file:
Step 3:
Save the file into your "UberTheme > assets > css" folder as "style.css".
Writing the default.hbs File
We're now going to move into writing the actual templating code of your theme, starting with the "default.hbs" file. (See above for a summary of what this file is for).
Note: To differentiate between html tags and handlebars template tags, we will either use the term "html tags" or "template tags" so you know which type is being referred to.
Step 1:
In your preferred code editor, open your "default.hbs" file from the root folder of theme, i.e. "UberTheme".
Step 2:
Add the following code:
All we've done here is add the essential doctype, html, head and body tags. We've also added some basic meta tags to set the charset, enabled Chrome Frame (if available) or else Edge mode (highest available) for IE, and to initialize our responsive display.
Note: In the above code you'll also see two examples of how comments can be written in handlebars files (the "Document Settings" and "Responsive Meta Tags" comments). Comments are differentiated when there is an exclamation point added immediately after the opening of two sets of curly brackets, with the close of the comment marked by two closing sets of curly brackets. Here's another example:
Step 3:
Add the following snippet just above the {{! Responsive Meta Tags }} code:
This adds page specific meta html tags.
Step 4:
Add the following snippet above the {{! Responsive Meta Tags }} code and directly below the page meta html tag lines that you previously added:
This adds the external link to your stylesheet.
Note: You don't need a full path to your stylesheet, only a path relative to the root folder of your theme.
Step 5:
Add the following above the closing </head> html tag:
Ghost uses this tag to output important style and meta data in the head section.
Note: For those with a WordPress theming background, you could compare this to the inclusion of wp_head() in all theme <head> sections.
Step 6:
Replace the the <body> html tag with the following code:
This template tag will output a different CSS class name depending on which area of the site is being loaded:
On the home page: "home-template"
On pages of older posts reached via pagination: "archive-template"
On single posts: "post-template"
Step 7:
Below the <body class="{{body_class}}> html tag that you added during step 6 and directly above the </body> html tag, add the following code:
Wherever you place the {{{body}}} tag in your "default.hbs" file is where your main content will be displayed, i.e. your latest post list or single post view.
We have also added a div with the wrapper_uber class name we will style later as a wrapper, using it to control the width and other styling of the theme's main content area.
Note: All CSS classes should include namespacing to ensure they don't clash with any other styles the site might be loading. In this case, we are appending all class names with _uber.
Important: It is very important the {{{body}}} tag is surrounded by triple curly brackets, as this prevents the values returned here from being escaped. If you didn't use triple curly brackets here you would get a load of HTML displayed on your screen instead of actual content.
Step 8:
Directly above the </body> html tag add the following code:
Much like the {{ghost_head}} tag we added above, this {{ghost_foot}} template tag must be included in order to output important scripts and data.
Step 9:
Save the "default.hbs" file.
Your "default.hbs" file should now look like this:
Testing Your "default.hbs" File
You're now ready to test your "default.hbs" template file and make sure everything is correct.
In order to do this, you'll just need to let Ghost know you want it to load the "default.hbs" template.
Step 1:
Open up both your "index.hbs" and "post.hbs" files in your code editor.
Step 2:
Add the following code to each and then save:
When Ghost sees the {{!< default}} tag it will know you want to wrap the page in the code from the "default.hbs" template.
Step 3:
Now, to test your "default.hbs" file, go back to the front end of your Ghost site, typically located at http://localhost:2368/ghost, and refresh the page.
Step 4:
Where before you saw just a blank white browser window, you should now see the window's background colour converted to a light grey.
If you see this, you have verified that your stylesheet is loading properly.
If the browser window is still white, double check that the location and name of your stylesheet is entered correctly in the <link> line you added to your <head> section.
Step 5:
Use your browser to view the page source. If it looks like this you have successfully created your "default.hbs" file:
Note: You may find that your title and meta description content appears differently when you view your page source. If so, that's perfectly normal as the data in those fields is drawn from the blog title and blog description as entered in the Ghost admin "Settings > General" page.
Coming Up Next
Although this is the end of the second installment, we're not done with the templating stage of creating your Ghost theme just yet.
However, we are ready to start adding some content so that it can be displayed on a page and so that we can keep testing the setup of our templates as we go along.
The next stage of our tutorial series continues and finalizes the templating process. You'll learn how to add template tags and markup, finalize your theme's three main template files, and add the template files which place a common header and footer in your theme. By the end of the next part, the templating process of creating your theme will be complete.