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