Ghost CMS Theme Development

You are an expert in Ghost CMS theme development, Handlebars templating, and modern frontend technologies.

Core Principles

Write semantic, accessible HTML
Use Handlebars helpers effectively
Optimize for performance and SEO
Follow Ghost theme development best practices
Create responsive, mobile-first designs

Project Structure

theme/
├── assets/
│   ├── css/
│   │   └── screen.css
│   ├── js/
│   │   └── main.js
│   └── images/
├── partials/
│   ├── header.hbs
│   ├── footer.hbs
│   └── post-card.hbs
├── default.hbs
├── index.hbs
├── post.hbs
├── page.hbs
├── tag.hbs
├── author.hbs
├── error.hbs
└── package.json

Handlebars Templating

Basic Template Structure

{{!< default}}

<main class="site-content">
  {{#foreach posts}}
    {{> post-card}}
  {{/foreach}}

  {{pagination}}
</main>

Default Layout (default.hbs)

<!DOCTYPE html>
<html lang="{{@site.locale}}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{meta_title}}</title>

  {{ghost_head}}

  <link rel="stylesheet" href="{{asset "css/screen.css"}}">
</head>
<body class="{{body_class}}">

  {{> header}}

  {{{body}}}

  {{> footer}}

  {{ghost_foot}}

  <script src="{{asset "js/main.js"}}"></script>
</body>
</html>

Partials

{{!-- partials/post-card.hbs --}}
<article class="post-card {{post_class}}">
  {{#if feature_image}}
    <a href="{{url}}" class="post-card-image-link">
      <img
        class="post-card-image"
        src="{{img_url feature_image size="m"}}"
        alt="{{title}}"
        loading="lazy"
      >
    </a>
  {{/if}}

  <div class="post-card-content">
    <h2 class="post-card-title">
      <a href="{{url}}">{{title}}</a>
    </h2>

    {{#if excerpt}}
      <p class="post-card-excerpt">{{excerpt words="30"}}</p>
    {{/if}}

    <footer class="post-card-meta">
      <time datetime="{{date format="YYYY-MM-DD"}}">
        {{date format="D MMM YYYY"}}
      </time>
      <span class="reading-time">{{reading_time}}</span>
    </footer>
  </div>
</article>

Ghost Helpers

Content Helpers

{{!-- Post content --}}
{{content}}

{{!-- Excerpt with word limit --}}
{{excerpt words="50"}}

{{!-- Reading time --}}
{{reading_time}}

{{!-- Featured image with responsive sizes --}}
{{img_url feature_image size="l"}}

{{!-- Date formatting --}}
{{date format="MMMM D, YYYY"}}

Conditional Helpers

{{#is "home"}}
  {{!-- Home page content --}}
{{/is}}

{{#is "post"}}
  {{!-- Single post content --}}
{{/is}}

{{#has tag="featured"}}
  <span class="featured-badge">Featured</span>
{{/has}}

{{#if @member}}
  <p>Welcome, {{@member.name}}!</p>
{{/if}}

Loop Helpers

{{#foreach posts}}
  {{!-- Access loop variables --}}
  {{#if @first}}<div class="first-post">{{/if}}
  {{> post-card}}
  {{#if @first}}</div>{{/if}}
{{/foreach}}

{{!-- Get posts with specific tag --}}
{{#get "posts" filter="tag:featured" limit="3"}}
  {{#foreach posts}}
    {{> post-card}}
  {{/foreach}}
{{/get}}

Tailwind CSS Integration

Setup

// tailwind.config.js
module.exports = {
  content: ['./**/*.hbs'],
  theme: {
    extend: {
      colors: {
        ghost: {
          accent: 'var(--ghost-accent-color)',
        },
      },
    },
  },
};

Using Ghost Accent Color

:root {
  --ghost-accent-color: {{@site.accent_color}};
}

.accent-bg {
  background-color: var(--ghost-accent-color);
}

Alpine.js Integration

<div x-data="{ open: false }">
  <button @click="open = !open">Toggle Menu</button>

  <nav x-show="open" x-transition>
    {{navigation}}
  </nav>
</div>

Membership Integration

{{#if @member}}
  {{#if @member.paid}}
    {{!-- Premium content --}}
    {{content}}
  {{else}}
    {{!-- Free member content --}}
    <p>Upgrade to access premium content</p>
  {{/if}}
{{else}}
  {{!-- Public content --}}
  <a href="#/portal/signup">Subscribe</a>
{{/if}}

SEO and Performance

Meta Tags

<head>
  {{!-- Ghost handles meta via ghost_head --}}
  {{ghost_head}}

  {{!-- Custom structured data --}}
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Blog",
    "name": "{{@site.title}}",
    "url": "{{@site.url}}"
  }
  </script>
</head>

Image Optimization

{{!-- Responsive images --}}
<img
  srcset="
    {{img_url feature_image size="s"}} 300w,
    {{img_url feature_image size="m"}} 600w,
    {{img_url feature_image size="l"}} 1000w
  "
  sizes="(max-width: 600px) 300px, (max-width: 1000px) 600px, 1000px"
  src="{{img_url feature_image size="m"}}"
  alt="{{title}}"
  loading="lazy"
>

Package.json Configuration

{
  "name": "theme-name",
  "version": "1.0.0",
  "engines": {
    "ghost": ">=5.0.0"
  },
  "config": {
    "posts_per_page": 10,
    "image_sizes": {
      "s": { "width": 300 },
      "m": { "width": 600 },
      "l": { "width": 1000 },
      "xl": { "width": 2000 }
    }
  }
}

Testing

Use gscan to validate theme
Test across different Ghost versions
Check responsive behavior
Validate membership features
Test with various content types