Sign in Subscribe
By Jon Frelund in ghost —

Creating a Ghost Theme from Scratch

Ghost is an open-source blogging platform known for its speed, simplicity, and focus on content 1. One of the best things about Ghost is that it is highly customizable. By creating a custom theme, you can achieve a unique look and feel for your website, improve performance, and have greater control over the design 2. This article will guide you through the process of creating a Ghost theme from scratch.

Getting Started

Before we begin, ensure you have the following tools installed:

  • Node.js: A JavaScript runtime environment that executes JavaScript code outside a web browser.
  • npm (Node Package Manager): A package manager for JavaScript, included with Node.js. It allows you to install and manage software packages (like Ghost CLI).
  • Ghost CLI (Command Line Interface): A command-line tool for interacting with Ghost. You'll use it to install and manage your local Ghost instance.
  • A code editor: A text editor specifically designed for writing and editing code. Popular choices include Visual Studio Code, Sublime Text, and Atom.

To install Node.js, npm, and Ghost CLI, you can follow these steps 1:

  1. Download Node.js: Visit the official Node.js website and download the installer for your operating system.
  2. Install Node.js: Run the installer and follow the on-screen instructions. This will also install npm.
  3. Install Ghost CLI: Open your terminal and run the command npm install ghost-cli@latest -g. This will install Ghost CLI globally on your system.

Once you have these tools installed, you can create a new Ghost theme.

Creating a New Ghost Theme

To create a new Ghost theme, we'll use the Ghost CLI. Open your terminal and run the following command:

ghost install local

This will install a local instance of Ghost on your computer. Once the installation is complete, you can start Ghost by running:

ghost start

Now that Ghost is running, we can create a new theme. Navigate to the content/themes directory of your Ghost installation and create a new folder. You can name this folder anything you want, but for this example, we will name it my-theme.

Inside the my-theme folder, create the following files:

  • package.json
  • index.hbs
  • post.hbs

These are the three required files for a Ghost theme 3. In addition to these, you can create other template files to customize different aspects of your website, such as tag.hbs for tag archives and author.hbs for author archives 4. Let's take a look at each of the required files in more detail.

package.json

The package.json file contains metadata about your theme, including its name, version, author, and description. It also lists the theme's dependencies 3.

Here's an example of a package.json file 3:

JSON

{
  "name": "my-theme",
  "version": "1.0.0",
  "description": "My Ghost theme",
  "author": "Your Name",
  "license": "MIT",
  "engines": {
    "ghost-api": "v3"
  }
}

index.hbs

The index.hbs file is the template for the homepage of your Ghost blog. It contains the HTML code that displays the list of posts on the homepage, as well as other types of content like tag archives and author archives 4.

Here's an example of an index.hbs file:

HTML

{{!< default}}

<main id="site-main" class="site-main outer">
    <div class="inner posts">
        {{#foreach posts}}
            {{> "post-card"}}
        {{/foreach}}
    </div>
</main>

This code will loop through all the posts on your blog and display them using the post-card partial. We'll create this partial later in the "Partials" section.

post.hbs

The post.hbs file is the template for individual posts on your Ghost blog. It contains the HTML code that displays the content of a post.

Here's an example of a post.hbs file:

HTML

{{!< default}}

<article class="post-full post tag-getting-started {{post_class}}">
    <header class="post-full-header">
        <section class="post-full-meta">
            <time class="post-full-meta-date" datetime="{{date format='YYYY-MM-DD'}}">
                {{date format="D MMMM YYYY"}}
            </time>
        </section>
        <h1 class="post-full-title">{{title}}</h1>
    </header>

    {{#if feature_image}}
        <figure class="post-full-image">
            <img
                srcset="{{img_url feature_image size="s"}} 300w,
                        {{img_url feature_image size="m"}} 600w,
                        {{img_url feature_image size="l"}} 1000w,
                        {{img_url feature_image size="xl"}} 2000w"
                sizes="(max-width: 800px) 400px,
                        (max-width: 1170px) 1170px,
                        100vw"
                src="{{img_url feature_image size="xl"}}"
                alt="{{title}}"
            />
        </figure>
    {{/if}}

    <section class="post-full-content">
        <div class="post-content outer">
            <div class="inner">
                {{content}}
            </div>
        </div>
    </section>
</article>

This code displays the title, date, and content of a post. It also displays the feature image if one is set.

default.hbs

The default.hbs file is a crucial part of any Ghost theme. It acts as the base template for all other templates 4. This file typically contains the basic HTML structure, such as the <html>, <head>, and <body> tags, as well as common elements like the header and footer.

Here's an example of a default.hbs file 4:

HTML

<!DOCTYPE html>
<html lang="{{@site.locale}}">
<head>
    {{ghost_head}}
</head>
<body class="{{body_class}}">
    {{{body}}}
    {{ghost_foot}}
</body>
</html>

In this example, {{ghost_head}} and {{ghost_foot}} are Ghost helpers that inject necessary metadata and scripts into the <head> and before the closing </body> tag, respectively. The {{{body}}} helper is where the content from other templates, like index.hbs and post.hbs, is inserted.

routes.yaml

The routes.yaml file defines the URL structure of your Ghost website and configures different content collections and their URLs 5.

Here's an example of a routes.yaml file 5:

YAML

routes:
  /:
    template: index
  /about/:
    template: about
collections:
  /:
    permalink: /{slug}/
    template: index
taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

This example defines the homepage (/) to use the index.hbs template and an about page (/about/) to use the about.hbs template. It also defines how individual posts, tags, and author pages are displayed in the URL structure.

Partials

Partials are reusable components that can be used to avoid code duplication in your Ghost theme 6. They are like building blocks that you can use to create different parts of your website.

For example, you could create a post-card partial to display a summary of a blog post. This partial could then be used on the homepage, in tag archives, and in author archives.

Here's an example of a post-card partial 6:

HTML

<article class="post-card {{classes}}">
    <a class="post-card-image-link" href="{{url}}">
        <img class="post-card-image" srcset="{{img_url feature_image size="s"}} 300w,
                       {{img_url feature_image size="m"}} 600w,
                       {{img_url feature_image size="l"}} 1000w,
                       {{img_url feature_image size="xl"}} 2000w"
            sizes="(max-width: 1000px) 400px, 800px"
            src="{{img_url feature_image size="m"}}"
            alt="{{title}}"
        />
    </a>
    <div class="post-card-content">
        <a class="post-card-content-link" href="{{url}}">
            <header class="post-card-header">
                {{#if primary_tag}}
                    <span class="post-card-primary-tag">{{primary_tag.name}}</span>
                {{/if}}
                <h2 class="post-card-title">{{title}}</h2>
            </header>
            <section class="post-card-excerpt">
                {{excerpt words="30"}}
            </section>
        </a>
        <footer class="post-card-meta">
            {{#if author.url}}
                <a href="{{author.url}}" class="author-profile-image"><img class="author-profile-image" src="{{img_url author.profile_image size="xs"}}" alt="{{author.name}}" /></a>
            {{/if}}
            <span class="post-card-byline-content">
                <span class="post-card-byline-name">{{author.name}}</span>
                <span class="post-card-byline-date">{{date format="D MMM YYYY"}}</span>
            </span>
        </footer>
    </div>
</article>

This partial displays the feature image, title, excerpt, author, and date of a post.

Creating the Required Parts of a Ghost Theme

Now that we've created the necessary files, let's create the essential parts of a Ghost theme: the header, footer, sidebar, and content area. When creating these parts, you'll work with different contexts and helpers in your Ghost theme 3.

  • Contexts: Contexts determine what data is available to you in a template. For example, in the post.hbs template, you have access to the post context, which provides information about the current post, such as its title, content, and author.
  • Helpers: Helpers are functions that help you manipulate and display data in your templates. For example, the foreach helper allows you to loop through a list of posts, and the if helper allows you to conditionally display content.

The header is the topmost part of your Ghost blog. It typically contains the blog's logo, navigation menu, and search bar.

Here's an example of code you can add to the default.hbs file to create a header:

HTML

<header class="site-header outer">
    <div class="inner">
        <div class="site-header-content no-image">
            <h1 class="site-title"><a href="{{@site.url}}">{{@site.title}}</a></h1>
            {{#if @site.description}}
                <h2 class="site-description">{{@site.description}}</h2>
            {{/if}}
        </div>
    </div>
</header>

This code displays the blog's title and description in the header.

The footer is the bottommost part of your Ghost blog. It typically contains copyright information, links to social media pages, and a contact form.

Here's an example of code you can add to the default.hbs file to create a footer:

HTML

<footer class="site-footer outer">
    <div class="site-footer-content inner">
        <section class="copyright"><a href="{{@site.url}}">{{@site.title}}</a> &copy; {{date format="YYYY"}}</section>
        <nav class="site-footer-nav">
            <a href="{{@site.url}}/">{{t "Home"}}</a>
            {{navigation type="secondary"}}
        </nav>
        <div><a href="https://ghost.org/" target="_blank" rel="noopener">Powered by Ghost</a></div>
    </div>
</footer>

This code displays copyright information, a link to the homepage, and a link to the Ghost website in the footer.

The sidebar is a vertical column that is typically displayed on the right side of the content area. It can be used to display a variety of information, such as a list of recent posts, a tag cloud, or a search bar.

Here's an example of code you can add to the post.hbs file to create a sidebar:

HTML

<aside class="read-next outer">
    <div class="inner">
        <h4 class="read-next-header">{{t "Read Next"}}</h4>
        <div class="read-next-feed">
            {{#get "posts" limit="3" filter="id:-{{id}}" include="authors" as |readnext|}}
                {{#foreach readnext}}
                    {{> "post-card"}}
                {{/foreach}}
            {{/get}}
        </div>
    </div>
</aside>

This code displays a list of three recent posts in the sidebar.

Content Area

The content area is the main area of your Ghost blog where the content of posts and pages is displayed.

Here's an example of code you can add to the post.hbs file to create a content area:

HTML

<section class="post-full-content">
    <div class="post-content outer">
        <div class="inner">
            {{content}}
        </div>
    </div>
</section>

This code displays the content of a post in the content area.

Customizing a Ghost Theme

Once you've created the required parts of your Ghost theme, you can customize it by changing the colors, fonts, and layout. You can also add new features to the theme.

To customize the theme, you can edit the CSS files in the assets/css directory. You can also edit the HTML files in the theme's root directory.

Here are some examples of how you can customize your Ghost theme:

  • Change the colors: You can change the colors of your theme by editing the CSS variables in the global.css file. For example, you could change the primary color of your theme by changing the value of the --ghost-accent-color variable.
  • Change the fonts: You can change the fonts of your theme by editing the @font-face rules in the screen.css file. For example, you could change the body font of your theme by adding a new @font-face rule that imports a custom font.
  • Change the layout: You can change the layout of your theme by editing the HTML structure of your templates. For example, you could change the layout of the homepage by editing the index.hbs file.
  • Add new features: You can add new features to your theme by writing custom JavaScript code. For example, you could add a feature that allows users to share posts on social media.

Uploading and Activating a Theme

Once you've finished customizing your theme, you need to upload and activate it in Ghost. To do this, follow these steps 7:

  1. Zip your theme folder: Compress the entire my-theme folder into a zip file.
  2. Upload the theme: In your Ghost admin panel, go to Settings > Design. Click the Upload theme button and select the zip file you created.
  3. Activate the theme: Once the theme is uploaded, click the Activate button to make it the active theme for your website.

Conclusion

This article has provided a comprehensive guide to creating a Ghost theme from scratch. We've covered the essential files, the required parts of a theme, and how to customize and activate your theme.

Creating a custom Ghost theme offers numerous benefits, including a unique look and feel, improved performance, and greater control over your website's design. By following the steps outlined in this article, you can create a theme that perfectly matches your vision and enhances your online presence. I encourage you to explore Ghost theme development further and unlock the full potential of this powerful platform.

Works cited

1. How to make a Ghost theme - Thoughtbot, accessed February 20, 2025, https://thoughtbot.com/blog/how-to-make-a-ghost-theme
2. Customizing your brand and design settings - Ghost, accessed February 20, 2025, https://demo.ghost.io/design/
3. Essential concepts to know when building a Ghost theme, accessed February 20, 2025, https://ghost.org/tutorials/essential-concepts/
4. Ghost Handlebars Theme Structure - Developer Documentation, accessed February 20, 2025, https://ghost.org/docs/themes/structure/
5. Ghost Theme Structure & Organization | Bright Themes, accessed February 20, 2025, https://brightthemes.com/blog/ghost-theme-structure
6. A complete guide to partials in Ghost, accessed February 20, 2025, https://ghost.org/tutorials/partials/
7. How to Make Custom Templates in Ghost Themes, accessed February 20, 2025, https://brightthemes.com/blog/ghost-custom-templates

Subscribe to FRELUND

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.
jamie@example.com
Subscribe