Customizing a Ghost Theme

Ghost-based sites 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 Ghost theme.  You get the look and feel you want without having to heavily optimize the site 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 Ghost theme, it’s far more common to only tweak or edit a few aspects of an existing theme than to dive into full-on Ghost theme development.

Before you begin, ensure you really need to maintain a Ghost 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 Ghost themes also allow further customization through options like editing CSS variables by specifying 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 Customizing a Ghost Theme

Turn Your Ghost Blog Into a Full Website

By using the Mindspun 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

Ghost themes allow you to control any HTML, CSS, or JavaScript on a page. This gives you complete control over the design of your site. Customize your site’s layout, post structure, and even when you publish. A Mindspun theme empowers you to create a unique website.

Easy to Install and Set Up

Mindspun 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 Mindspun 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. Below 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 required to get going. Don’t let this deter you, even if you haven’t done much web development.  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 12.x (Node v12 Erbium 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

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

Install the Ghost CLI & 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 ghostghost 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 terminal, 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.

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\clydeghost restart

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

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.

 

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 through theme customizations.  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.

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.

Change the Footer Background Color

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.

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.

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.

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.

 

Conclusion

This post showed you how to customize a Ghost theme that’s suitable for any 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. Now you’re well on your way to making a site that reflects your vision. Happy theming!