This chapter will be a guide to kickstart your first Ghost theme from scratch.
However, we won't be just walking you through designing one or two specific example themes, because then all you would know would be just how to make one or two specific themes. Instead, we're aiming to equip you to build any kind of theme you might want to for Ghost. In order to do this, we're not going to focus directly on design, but rather on all the little tools and tricks available through the Ghost theme API that you currently have to work with as a designer.
First, we'll cover the spaces on a Ghost blog you get to control via a theme design, such as your main index area, your individual posts and so on. We'll refer to each of these as themeable areas. Secondly, we'll look at the visual building blocks Ghost currently offers you to put in those areas, that is, items such as blog titles, logos, and post content you can place in your theme.
We'll then go over a summary of the extra tools that Ghost gives you to work with to format theme content differently depending on conditions such as whether a viewer is looking at a featured post, an item with a particular tag, and so on. We'll also cover what Ghost doesn't include at this stage.
From here, you'll plan out your design concept in the easiest possible way by going through a Quick start theme quiz where your answers will form the basis of your design.
Once you know how to work with the full range of theming options Ghost gives you, you'll have the knowledge to select from those options and assemble themes in as many different ways as you choose.
Your first step in the actual production of your theme will be to create a theme shell; an unstyled theme with all the essentials in place that you can mold into any type of theme you want. After creating this shell, you'll add test content to your local Ghost installation, activate your new theme and prepare to move onto the next stage.
This chapter includes the following topics:
- The currently available design options in Ghost
- Ghost's themeable areas
- Ghost's theme building blocks
- Extra design tools in Ghost
- What Ghost doesn't include
- Quick start theme quiz
- Creating your theme shell
- Setup file and folder structure
- Running the first CSS and JS compile into theme
- Adding basic code to template files and package.json
- Adding test content and activating your theme
We won't get into the technicalities of how to actually code these aspects up right away, but instead just begin with the information you need to hash out your design concept.
Then, after we work through putting together your design concept, we'll get into which files to create and what code to write in order to take that concept into production.
The different themeable areas of Ghost are as follows:
- Default (required): This is a wrapper around all your other theme areas. It typically holds your header, footer, and any other elements that should appear everywhere throughout your theme.
- Index (required): This is a paginated list of your posts beginning on your homepage with the most recent.
- Post (required): Display of an individual post. Posts can be tagged.
- Tag Archive (optional but recommended): This is a list of all posts under a specific selected tag. If no theme styling is included, tag archives will use the code from the
Indexfile. - Page (optional but recommended): This is a display of a static page. If no theme styling is included, pages will display the same way as your Post area.
With Ghost using Handlebars, many attributes of the blog settings are available, so a theme can pull them dynamically. For example, a blog title is something you can change in your settings, so, instead of then needing to go change the title in your theme, you can use Handlebars attributes so it will update on the blog as well without any change in code.
New attributes are being added constantly to Ghost, but here are some of them along with where they can be used in the themes:
- The following attributes are available everywhere:
- The following attributes are only available in the Index, Post, and Tag Archive areas:
- The following attribute is only available in the Index, Post, and Tag Archive areas:
- The following attributes are only available in Index and Tag Archive areas:
- The following attributes are only available in the Post and Page areas:
- Author name
- Author location
- Author website
- Author bio
- Author image
- Author cover
- The following attributes are only available in the Tag Archive area:
The extra design tools available are as follows:
- The
Featuredpost status: When a user sets a post to this status, it will have a class offeaturedadded to it, and can be identified with a Handlebars conditional check. This is used to display featured posts before regular posts, and/or to style featured posts in a different way. - The
{{#has}}helper: This tool checks if any post has (or doesn't have) a particular tag and modifies its display based on the result. This is used to create customized displays for things such as posts tagged asvideo,image,text, and so on. - Content blocks: They allow elements of the default wrapper to be modified through other themeable areas. For example, on a single post, check for a
videotag, and if found, alter the layout width to allow for widescreen playback. @firstand@last: They identify the first and last post in any index or tag archive list. They are used to create enhanced layouts or highlight opening and closing posts.@evenand@odd: They identify every second post alternately. They are used to zebra stripe.columns,@rowStart, and@rowEnd: They tell Ghost how many columns are in your layout, will keep track of your posts, and allow you to output which ones are at a row start and which are at a row end.
There are also a few things that are common to other blogging platforms that Ghost doesn't, as of yet, include. Some are planned on the roadmap, some are likely to arrive via apps created by the community, and some are not on the horizon at all.
While these items might appear in the not too distant future, we won't be using them in this theming guide, because even if we did, it would be via incorrect (hackish) methods that would then have to be redone in the future. It's much better to wait until properly crafted updates to Ghost or plugins are released that will handle the job in the correct fashion. The following items are currently excluded by Ghost:
- Menus: These are on the roadmap for Ghost core, but not until a few versions down the track. However, it's highly likely a plugin, or several plugins, will be released by the community to handle this shortly after the release of apps.
- Sidebar Widgets: Ghost doesn't have a means to drag-and-drop custom content into positions such as sidebars, so you should plan to work with the content items listed previously. However, again it's very likely that apps will appear to handle this type of functionality.
- Comments: Ghost has determined (from the outset) that inclusion of a comments system in core was unnecessary given the many quality comments systems available, such as Disqus. It's possible to integrate Disqus into themes via code; however, apps to handle this automatically for users are likely to become available very soon.