# Ghost Theme Migration - Casper to Source
**Task:** Migrate Ghost CMS from Casper theme to Source theme v1.5.2
**Status:** ✅ COMPLETE
**Date:** March 21, 2026
**Chronicler:** #38
---
## Problem Statement
Casper theme's CSS specificity was creating hours of debugging battles:
- Even `html body .class !important` was being overridden by Casper's base styles
- `.gh-canvas` grid system fought full-width layouts
- Required inline `!important` on every font-size property
- Made future customization painful and time-consuming
---
## Solution
Migrated to Source theme v1.5.2 with custom template for homepage rendering.
### Why Source Theme?
- Official Ghost core team theme
- Minimal CSS opinions (designed as blank canvas)
- Guaranteed compatibility with Ghost updates
- HTML cards span naturally without grid constraints
- Uses CSS variables for easy theming
---
## Implementation
### Phase 1: Backup Everything
**Files backed up:**
1. Theme: `casper-firefrost.tar.gz`
- Location: `/home/architect/ghost-backups/` on Ghost VPS
- Size: 151 bytes (tar.gz of theme directory)
2. Content & settings: JSON export
- Downloaded via Ghost Admin → Settings → Import/Export → "Content & settings"
3. Routes: `routes.yaml`
- Downloaded from Ghost Admin → Settings → Labs → Routes
4. Redirects: `redirects.yaml`
- Contains Discord redirect: `/discord: https://discord.gg/hDHvKfqhKs`
### Phase 2: Install Source Theme
1. Downloaded Source v1.5.2 from GitHub
2. Packaged as `source-theme-ready.zip`
3. Uploaded via Ghost Admin → Design & branding → Upload theme
4. Activated theme
### Phase 3: Create Custom Template (Gemini's Solution)
**Problem:** Source's default `home.hbs` template displays blog posts, not page content
**Solution:** Create custom template that renders page content
**File:** `/var/www/firefrost/content/themes/source-theme-ready/custom-home.hbs`
```handlebars
{{!< default}}
{{#post}}
{{content}}
{{/post}}
```
**Also copied to:** `/var/www/firefrost/content/themes/source/custom-home.hbs` (for fallback)
### Phase 4: Update Routes
**File:** `/var/www/firefrost/content/settings/routes.yaml`
```yaml
routes:
/:
data: page.home
template: custom-home
collections:
/blog/:
permalink: /blog/{slug}/
template: index
taxonomies:
tag: /tag/{slug}/
author: /author/{slug}/
redirects:
/discord: https://discord.gg/hDHvKfqhKs
```
**Key change:** `template: custom-home` (was `template: home`)
### Phase 5: Restart Ghost
```bash
sudo systemctl restart ghost_firefrostgaming-com
```
---
## Results
✅ **Homepage renders perfectly** with Fire/Frost branding
✅ **Zero CSS specificity battles**
✅ **Full-width HTML cards work without hacks**
✅ **Clean foundation for future customization**
✅ **Official theme = guaranteed Ghost updates**
---
## Navbar Customization
### Problem 1: Default Layout
Source theme defaults to centered logo with navigation on sides. We needed:
- Logo left
- Navigation links center
- Action buttons (Search, Sign in, Subscribe) right
### Solution 1: Custom CSS
Added to Ghost Admin → Settings → Design & branding → Site-wide head:
```css
/* Dark background for navbar */
#gh-navigation {
background-color: #1a1a1a !important;
border-bottom: 1px solid #333 !important;
}
/* Flexbox layout */
.gh-navigation-inner {
display: flex !important;
align-items: center !important;
justify-content: space-between !important;
}
/* Logo left, nav center, actions right */
.gh-navigation-brand { order: 1 !important; }
.gh-navigation-menu { order: 2 !important; flex: 1 !important; justify-content: center !important; }
.gh-navigation-actions { order: 3 !important; }
```
### Problem 2: Sign In Button Disappeared
**Root cause:** `{{t "Sign in"}}` translation helper was rendering empty string, creating invisible 0-width element
**Diagnosis:** Gemini consultation revealed Ghost localization quirk
### Solution 2: Hardcode Text + Custom Class
**Modified:** `/var/www/firefrost/content/themes/source-theme-ready/partials/components/navigation.hbs`
**Changed:**
```handlebars
{{t "Sign in"}}
Sign in
```
**CSS added:**
```css
.gh-navigation-members .ffg-signin-link {
display: inline-block !important;
visibility: visible !important;
opacity: 1 !important;
color: #ffffff !important;
font-weight: 500 !important;
text-decoration: none !important;
margin-right: 0.5rem !important;
}
```
---
## Key Learnings
1. **Source theme's home.hbs is blog-focused** - custom template required for page content
2. **`{{t}}` helper can fail** - renders empty string, creating invisible elements
3. **Gemini excels at Ghost debugging** - caught translation helper issue Claude missed
4. **Always backup before theme migrations** - we had complete rollback capability
5. **Test after each change** - incremental fixes easier to debug
---
## Files Modified on Ghost VPS
**Created:**
- `/var/www/firefrost/content/themes/source-theme-ready/custom-home.hbs`
- `/var/www/firefrost/content/themes/source/custom-home.hbs`
- `/home/architect/ghost-backups/casper-firefrost.tar.gz`
**Modified:**
- `/var/www/firefrost/content/themes/source-theme-ready/partials/components/navigation.hbs`
- `/var/www/firefrost/content/settings/routes.yaml`
**Ghost Admin settings:**
- Site-wide head CSS (navbar styling, typography, grid fixes)
---
## Rollback Procedure (If Needed)
1. Ghost Admin → Design & branding → Change theme to `casper-firefrost`
2. Restore routes.yaml from backup
3. Restart Ghost: `sudo systemctl restart ghost_firefrostgaming-com`
All backups available on Ghost VPS at `/home/architect/ghost-backups/`
---
## Future Maintenance
**When Source theme updates:**
1. Download new version from GitHub
2. Copy `custom-home.hbs` into new theme directory
3. Copy navigation.hbs modifications (Sign in fix)
4. Upload and test in Ghost Admin
5. Activate when verified
**Custom files to preserve:**
- `custom-home.hbs` (95 bytes)
- Navigation fix in `partials/components/navigation.hbs`
---
## Credits
**Gemini consultation provided:**
- Custom template solution (custom-home.hbs)
- Sign in button diagnosis (`{{t}}` helper issue)
- Hardcoded text + custom class fix
**Files:**
- `/home/claude/gemini-ghost-migration-consultation.md`
- `/home/claude/gemini-signin-button-consultation.md`
---
**Status:** Migration complete, navbar functional, foundation solid. ✅
**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️