How to make a Ghost theme

Ghost is a publishing platform, great for personal and professional projects. Since 2013, the Ghost team has been building a robust tool for crafting content and sharing it with the digital world.

I first begun using Ghost as soon as it was publicly available and have seen it grow in to a fantastic solution for the needs of many clients and friends. In the second half of July 2017, Ghost v1.0.0 was released, and with it came numerous updates to the editing experience, a refreshed UI, and ever increasing control of how your work appears on social channels like Facebook and Twitter.

During the past year, we’ve had the opportunity to work with a number of clients looking to make their blogs better for their visitors, as well as their authors and staff. For many of them Ghost was a great fit, and you can check out their features page to see if what it has to offer meets your needs. Here’s a quick rundown of some key features that often fall in to the “must haves” when selecting a platform for a blog or site:

• Ghost is open source, but also has hosted options available if you don’t want to run your own server.
• It supports multiples roles for authors, editors, and admins for your whole team.
• You get strong out-of-the-box SEO including support for Facebook Open Graph, Twitter Cards, Schema.org, and AMP pages.
• Visitors and your team can subscribe to your site/blog by RSS, Email and Slack.
• Ghost has desktop apps for Mac, PC, and Linux.
• There’s more stuff including a post tags, scheduled publishing, JSON API, XML sitemaps.
• Lest we forget, Ghost theme architecture is flexible and easy to work with while allowing you to design your own creative and innovative designs.

Ghost isn’t a blunt instrument that works for every project, but can be the perfect tool for the right job. To that end, we created our own Ghost theme template to help creating your ghost theme a little easier.

Understanding the structure of Ghost themes

Ghost’s default theme is called Casper. It’s a great theme for getting started using ghost and making your own blog. However it’s got a substantial amount of code and structure making it less than ideal for as a starting place for creating new themes.

For this walk-through we’re going to be using thoughtbot’s ghost-theme-template, who’s structure is based on that of Casper, with all CSS, and non-essential html removed.

Core elements

Ghost (and subsequently Ghost themes) have a few core concepts from her which they build their structure. Most of these are standard elements of any blogging engine or platform.

• Posts: Referred to as “Stories” within user admin, posts are the base unit of Ghost. They’re blog posts… like the one you’re reading… right now.
• Pages: Pages are actually a sub-variant of posts. They have all the same properties as posts, but are excluded from the list/index of posts and won’t appear on the homepage.
• Authors: Authors are discrete objects that are associated posts and pages. The authors in a blog will also have their own pages including their avatar, description, and the post they’ve written.
• Navigation: Navigation is user customizable via the Ghost admin. You’re able to design a template within your theme for how the navigation manifests on each page.
• Tags: Tags can be associated with either posts or pages. Like authors, tags get their own page with all the posts that have the relevant tag, as well as an optional image and description. When tagging a post, the first tag in the series considered the “primary tag,” and can be given special features or privileges within the theme.
• Blog Attributes: The blog themselves can also have various attributes that are customized via the admin. This includes blog title, blog description, logos, and social icons.
• Email Signup: The enabling of email sign-up within the admin is currently optional and is by default deactivated. However, you can definitely add support for it within your theme. There’re two items associated with email subscription. First is a partial, that can be included anywhere throughout your site, which will generate a standard e-mail signup form. The second is a discrete email subscription page which is also customizable, comes pre-baked with a standard look and feel similar to that of the login page.

You also have the ability to customize the login pages for Ghost, but doing so is typically unneeded for the majority of projects.

Basic structure

The basic document and directory structure of Ghost themes is very similar to that of most simple web applications. Here’s an outline of the primary files that make up a Ghost theme.

• /assets: Your theme’s asset directory.
• /partials: Your theme’s partials directory.
  • loop.hbs: The “loop” is the primary post loop. This loop will be used any time you’re showing a list of post including the tags page, author page, and home page.
  • You can create any partials you want to use in multiple locations throughout the site. The ghost-theme-template uses this by having a site-header.hbs file to keep the top of the site consistent across the template.
• author.hbs: This is the author page. It contains the author’s name, avatar, bio, and a list of post the author has written.
• default.hbs: This is the main layout template file for all pages like the home, author, tag, and post pages.
• index.hbs: This is the index/home page. It contains the primary loop that will include all non-page posts.
• page.hbs: This is the template for pages (not posts). The overall structure of this is often very similar to the post template, but can be customized to be quite different.
• post.hbs: This is the template for your posts. Not much to say here; make it great!
• tag.hbs: The final template is for your blog’s tag pages. This page contains all of the post associated with a given tag.

Using Gulp with to build your Ghost theme

ghost-theme-template uses Gulp to add some basic quality of life additions to your ghost theme development workflow. It comes preconfigured with a few tasks to get you started. To get the theme up and running you’ll want to cd in to the theme directory and run npm install to install the theme’s dev dependencies. If this is your first time using Gulp, be sure to checkout the getting started docs.

gulp / gulp default

Once the project dependencies have been installed, you have a few tasks available to you. Running gulp will compile all SCSS files within the /scss directory. The theme also has Bourbon and Neat preconfigured, as well as Autoprefixer. No assembly required. Gulp will also run JSHint on any of your javascript within the theme’s /js directory. Once both the asset tasks have been run, Gulp will continue to watch for changes until terminated.

gulp deploy

So this is the cool part. Running gulp deploy will compile all of your assets, zip up your theme so you can upload it to ghost (themes can be added to ghost by way of the admin by uploading a zip file in settings), and will run Ghost’s official validator, GScan, which will scan your theme for common issues. If GScan detects any incompatibilities between your theme and Ghost, it will print the results to the console after the deploy has completed.

Publishing your Ghost blog

As you build your theme, you’ll want to be running Ghost locally so you are able to quickly iterate and review changes. Check out the Ghost documentation’s Set-up Guide for more info on running ghost locally, but you will first need to install the ghost-cli. Once your system is set up, it’s easy to dive in to your projects and generate new local blogs on the fly.

After you’ve finished your awesome new theme, you can either host your own ghost instance or use Ghost’s official hosted service (I do). Once your production app is set up, just upload your theme and your new blog is ready to go.

If you hit a snag, the Ghost Slack channel is a lively and helpful community full of people willing to help you get started.

GLHF 👻

Sincerely yours,
Will H McMahan