Creating a Ghost Theme

Creating a Ghost Theme

A Ghost site can be customized to look any way you want by modifying the theme.  Anything that can be done with HTML, CSS or JS can be done via a Ghoststead theme and - unlike with WordPress - unless you add a bunch of custom Javascript, customizing a theme doesn't heavily impact overall site speed.  You get the look and feel you want without having to heavily optimize it afterwards.

This article will describe the process of customizing an existing theme.  We won't get into creating a theme from scratch.  Although it's certainly possible to create a brand new theme, it's far more common to only need to tweak a few aspects from an existing theme.

Before you begin, ensure you really need to maintain a custom theme.  Many aspect the your site look and feel can be customized from the admin page of your site without modifying your theme.  Many available themes also allow further customization through options like CSS variables that allow you to specify brand and background colors, fonts, etc using "Code Injection" on the Ghost admin page.  See the documentation that came with your theme for available options.

Benefits of a GhostStead Theme

Customizing an existing theme has several advantages:

Turn Your Ghost Blog into a Full Website

By using the GhostStead theme, you’ll be able to customize your blog into the look and feel of a full website. The theme enables you to manipulate and customize how every element will appear.

Design Control

GhostStead themes allow you to control any HTML, CSS, or Javascript on the page—giving you full design control. Customize your site’s layout, post structure, or even when you publish. A GhostStead theme empowers you to create a unique website.

Easy to Use Editor

The WYSIWYG (what you see is what you get) editor allows you to see how your site will look as you edit, so there are no surprises—enabling you to create a clean, stylized, functional website easily.

Built-in SEO

Search Engine Optimization (SEO) is built into the theme and site, making it easier for you to rank high in search results. This also increases your website’s loading time by not requiring an additional plug-in, which ups your ranking.

Fast Page Loading Time

GhostStead servers ensure that your site will load quickly with virtually no downtime. And the GhostStead theme is built for page speed so that you won’t lose users. We offer several tips to speed up your website.

Easy to Install and Set Up

GhostStead themes take only a few minutes to install and set up. You won't need for plug-ins or third-party apps to be up and running quickly.

Core Elements of a Ghost Theme

A GhostStead theme has several core elements that will allow for customization. Because you will be determining the layout and design, you’ll want to understand each element’s function. These are some of the standard elements of an existing theme:

Posts: These are your blog articles. Posts are also referred to as “Stories” in the user admin. You’ll want to choose fonts and colors that are easy to read for this element.

Pages: Similar to posts, pages are static webpages that are excluded from the blog post feed. You can link to your pages in your menu, header, or footer. Your pages should have a similar layout to your posts.

Authors: Authors are objects associated with posts and pages. These tend to be the editors and administrators that write your content. You can assign authors to posts and pages. You can also customize how much information is shown about your author (bio, picture, name, etc.).

Tags: Similar to authors, Tags are descriptive words or categories you can are relevant to your posts and pages. By assigning tags, your users will easily be able to search your posts by tag searches. You can assign several tags to each post. The first tag is considered the primary. Customizing your theme, you can create special features and privileges for primary tags.

Navigation: Navigation is your menu links and breadcrumb links to help your users navigate your website. You can customize where and how your navigation links will appear to the user. Be sure to choose easy to read fonts, colors, and font sizes. Check out our navigation tips when customizing your site.

Blog Attributes: The blog attributes are the post title, description, logos, social icons. You can customize the look and layout of your blog attributes to reflect your website’s personality.

Email Signup: This is a form to allow your users to subscribe to an email newsletter or website promotions. You can customize where and how your signup is displayed.

Setup

There are several setup steps to get going, especially if you haven't done much web development.  Don't let this deter you.  Once everything set up, it's easy to make incremental changes.  If you've done some web development, this process should be familiar.

Install NodeJS

You are need at least a supported version of NodeJS and, unless there is a definitive reason why not, use the recommended version.  Currently 10.x (Node v10 Dubnium LTS).

NodeJS is free to download and available here, but a far better approach is to use the Node Version Manager (nvm) available here.  Javascript projects - which is what Ghost is - and the associated tools are notoriously finicky about requiring specific versions of tools.  If you do end up working with other JS projects,  you'll find yourself changing Node versions often and nvm really helps.

If you do go with nvm then switch to the recommended version of Node with the following command.

nvm install lts/dubnium
Use nvm to switch the NodeJS version

Now that NodeJS is installed, you can use the associated package manager npm to install everything else you need.

Install the Ghost CLI and a local version of Ghost

Installing a local version of Ghost saves a lot of development time later on. It's possible to build your theme and upload it to your site each time, but this process is painful to say the least.  A far better approach is to install Ghost locally and then link to your new theme using content\themes\<name>.

Install the Ghost CLI globally.

npm install ghost-cli@latest -g

Then install ghost.

mkdir ghost && cd ghost
ghost install local

Ghost is now running at http://localhost:2368/ghost/.

The ghost site runs in the background with the logs going to the content\logs directory.   To run Ghost in the foreground and print the logs to the termina, first stop the site:

ghost stop

and then start the development server:

npm run dev

When you want to stop the development server, just type Ctrl-C.

Start with a base theme

You can start with any theme you have.  Each theme can be downloaded from the Ghost admin panel under the Settings > Design.  You can download one from the marketplace or - more likely - download a theme that is already installed.

Download an existing theme

Regardless of which method you choose, a theme comes as .zip file.  When a theme is installed that .zip file is unzipped into content\themes underneath the ghost directory you installed.

We're going to start with the default theme "caspar" and create a modified theme named "clyde".  From the ghost directory you installed:

cp -a content\themes\caspar content\themes\clyde
ghost restart

The new theme is now available underneath installed themes on the Settings > Design page.

New Ghost theme is installed

Click 'Activate' and you're using your own custom theme! (albeit with no changes yet)

Pro Tip: If you want to maintain your custom theme in source control, you can check in the contents of the theme zip file and then create a symbolic link from content\themes to the directory in your repo.
Extra Credit: If you really want to start from the ground up, try our 'barebones' theme on github.
ghoststead/barebones
Contribute to ghoststead/barebones development by creating an account on GitHub.
The most minimal theme possible

Install theme dependencies

Themes have dependencies of their own - other NodeJS packages that are used with building that theme.  Install these using npm too.  From the theme directory, run:

npm install

Example Customizations

The sky's the limit here, you really control the entire Ghost UI.  Here are a couple of simple examples to get you started.

Change the theme name

Ghost disambiguates the theme by appending "(clyde)" to the name, but the name is still "casper".  Let's change it to just "clyde".

Open the file package.json from your theme directory in a text editor.

Editing package.json to change the theme name

Here you can set the name along with various other meta data about the theme.  Once you've made your changes, save the file, restart Ghost and reload your admin page.  You'll now see "clyde" as the name.

Most changes don't require you to restart Ghost.  Only changes to the theme meta data require a restart as the package.json file is only read once at startup.  Fortunately, meta data changes are relatively rare, usually just when you bump the version number.

We're going to change the page footer to use a Royal Blue background which is hex #2127BD.

Note: This example - unlike the previous one - is specific to the Casper theme.

The footer style is in the last section of the screen.css.

Original site-footer CSS

The background color uses a CSS variable which is define in global.css.  For simplicity, we'll just use the hex value directly.  Replace the background attribute with the hex value.

Modified site-footer CSS

Run the dev script via npm which runs the build process and also watches for subsequent file changes and automatically builds those too.

npm run dev

Go back to your browser, reload the page of one of your posts and scroll to the bottom.  You'll see a newly-royal-blue footer.

Royal Blue Ghost footer

Add a Call To Action to every page

As a final example, we'll add a call to action to every page in the site.  The previous examples changed the meta data and style of the theme but didn't change the underlying html.  This example will modify the page structure, by adding a simple <div> element right above the footer.

As you've probably noticed from your theme directory, pages are built using Handlebars (.hbs) template files.   Each type of page - post, author, tag, etc - has, or can have, its own template.   Each of these page templates also uses a layout template for things that are common to every page type.  The enclosing <html> tag, common head tags and site navigation are all part of the default layout template named default.hbs.

Add the following <div> right below the {{{body}}} variable and directly above the <footer> tag.

<div style="text-align:center; color:#fff; background:#005FFE">
    <h1 style="margin: 1em 0">Buy Now!</h1>
</div>

Of course, if you were making this change in practice, you wouldn't use inline styles. You'd put the style in the CSS as in the previous example.  Using inline styles here just simplifies the example.

If you haven't already done so, run the npm dev script to build the code.  The build will convert the Handlebars template files in HTML.

Reload any page on your site and you'll see your new - overly direct - CTA.

New Ghost Call-To-Action

Conclusion

This post showed you how to customize a theme suitable for any Ghost site.  We installed all the tools necessary for building, installing and debugging a Ghost theme. Finally, we provided three examples of modifications, changing the theme meta data, style and page structure respectively, which should get you well on your way to making any modification that you wish.   Happy theming.

Great! Check your inbox and click the link to confirm your subscription.
Please enter a valid email address!
You've successfully subscribed to GhostStead!
Could not sign up! Invalid sign up link.