How to Create a Custom Ghost Cms Theme from Scratch

by

Creating a custom theme for Ghost CMS allows you to tailor your website’s appearance and functionality to your specific needs. Whether you’re a developer or a hobbyist, building a theme from scratch gives you full control over your site’s design and user experience.

Getting Started with Ghost Theme Development

Before diving into coding, familiarize yourself with the Ghost theme architecture. Ghost themes are primarily built using Handlebars templates, along with CSS and JavaScript for styling and interactivity. The theme files are stored in a folder with a package.json file that defines theme metadata.

Setting Up Your Development Environment

To start creating your theme, set up a local environment with Ghost installed. You can use Ghost’s CLI to create a new theme directory:

ghost install local or follow the official Ghost documentation for detailed setup instructions.

Once Ghost is running locally, navigate to the content/themes folder and create a new folder for your theme. Inside, add a package.json file with basic metadata:

{
  "name": "my-custom-ghost-theme",
  "version": "1.0.0",
  "description": "A custom Ghost theme built from scratch",
  "author": "Your Name",
  "license": "MIT"
}

Creating the Core Files

The essential files for a Ghost theme include default.hbs, which serves as the main template, and optional partials like header.hbs and footer.hbs. Start with a basic default.hbs:

{{! This is the main template }}



  
  {{#if @page.title}}{{@page.title}}{{else}}{{@site.title}}{{/if}}
  


  {{> header}}
  

    {{#if @blog}}
      {{> index}}
    {{/if}}
    {{#if @post}}
      {{> post}}
    {{/if}}
  

  {{> footer}}

Adding Styles and Scripts

Create a assets folder inside your theme directory. Add a css folder with a style.css file to style your site. Link this stylesheet in your default.hbs as shown above.

You can also include JavaScript files for interactivity by adding a js folder and linking scripts similarly.

Customizing Templates and Partials

Use Handlebars syntax to customize your theme’s layout. Create partials like header.hbs and footer.hbs for reusable sections:

{{!-- header.hbs --}}


  
    
    

    
{{@site.title}}




{{!-- footer.hbs --}}


  
© {{year}} {{@site.title}}. All rights reserved.

Testing and Publishing Your Theme

Activate your theme in the Ghost admin panel. Visit your site to see your custom design in action. Debug and refine your templates, styles, and scripts as needed.

Once satisfied, package your theme by zipping the theme folder. Distribute or upload it to other Ghost instances following the official documentation.

Conclusion

Building a Ghost CMS theme from scratch empowers you to create a unique, tailored website. Start with the core templates, style your site, and customize layouts to fit your content. With practice, you’ll develop more complex themes that enhance user experience and showcase your creativity.