firefrost-operations-manual/docs/tasks/ghost-theme-migration

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

{{!< 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

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

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:

/* 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:

<!-- 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:

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