# 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}}

<main class="gh-main">
    {{#post}}
        {{content}}
    {{/post}}
</main>
```

**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
<!-- Before -->
<a href="#/portal/signin" data-portal="signin">{{t "Sign in"}}</a>

<!-- After -->
<a class="ffg-signin-link" href="#/portal/signin" data-portal="signin">Sign in</a>
```

**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** 💙🔥❄️
