docs: add Ghost theme migration task (Casper→Source)
Session 36 spent 2+ hours fighting Casper CSS specificity issues. Even html body .class element !important gets overridden. Gemini recommends migrating to Source theme (official, minimal, dev-friendly). Task includes complete migration plan with rollback strategy.
This commit is contained in:
103
docs/tasks/ghost-theme-migration/README.md
Normal file
103
docs/tasks/ghost-theme-migration/README.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Task: Migrate from Casper to Source Theme
|
||||
|
||||
## Priority: HIGH
|
||||
**Reason:** Current Casper theme creates CSS specificity battles that waste hours per session. Even `!important` rules with high specificity get overridden.
|
||||
|
||||
## Problem Statement
|
||||
Casper theme has opinionated CSS architecture that:
|
||||
- Overrides custom CSS even with `html body .class element !important` specificity
|
||||
- Fights full-width layouts with rigid `.gh-canvas` grid system
|
||||
- Requires inline `!important` on every font-size property as workaround
|
||||
- Makes future customization painful and time-consuming
|
||||
|
||||
**Evidence:** Session 36 spent 2+ hours debugging why `html body .ffg-custom-text h2 { font-size: 4rem !important; }` was overridden by Casper's base `h2 { font-size: 2.8rem; }` rule despite lower specificity.
|
||||
|
||||
## Recommended Solution
|
||||
Migrate to **Source theme** (official Ghost theme)
|
||||
|
||||
**Why Source:**
|
||||
- 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
|
||||
|
||||
**Alternatives considered:**
|
||||
- Ghost Starter Theme (too bare, requires building everything)
|
||||
- Edition (newsletter-focused, less suitable for gaming community)
|
||||
|
||||
## Migration Process (Zero Downtime)
|
||||
|
||||
### Pre-Migration Backup
|
||||
1. **Backup current Casper fork:**
|
||||
- Ghost Admin → Settings → Design & Branding → Customize
|
||||
- Click Advanced (top right) → Download
|
||||
- Store in /home/claude/ghost-backups/casper-fork-YYYY-MM-DD.zip
|
||||
|
||||
2. **Backup site content:**
|
||||
- Settings → Labs → Export your content
|
||||
- Save JSON file to /home/claude/ghost-backups/content-YYYY-MM-DD.json
|
||||
|
||||
3. **Backup routes:**
|
||||
- Settings → Labs → Routes → Download current routes.yaml
|
||||
- Save to /home/claude/ghost-backups/routes-YYYY-MM-DD.yaml
|
||||
|
||||
### CSS Variable Setup
|
||||
**BEFORE activating new theme**, add Fire/Frost branding variables to Site Header:
|
||||
|
||||
:root {
|
||||
/* Fire/Frost Brand Colors */
|
||||
--ffg-teal: #4ecdc4;
|
||||
--ffg-orange: #ff6b35;
|
||||
--ffg-purple: #a855f7;
|
||||
--ffg-gold: #FFD700;
|
||||
|
||||
/* Backgrounds */
|
||||
--ffg-bg-dark: #0f0f1e;
|
||||
--ffg-bg-darker: #0a0a1a;
|
||||
|
||||
/* Typography */
|
||||
--ffg-text-primary: #ffffff;
|
||||
--ffg-text-secondary: #a8dadc;
|
||||
--ffg-text-tertiary: #6b7280;
|
||||
}
|
||||
|
||||
### Theme Installation
|
||||
1. Download Source theme: https://github.com/TryGhost/Source
|
||||
2. Upload to Ghost: Settings → Design & Branding → Change Theme → Upload Theme
|
||||
3. Click Preview button (not Activate)
|
||||
|
||||
### QA Checklist (In Preview Mode)
|
||||
- [ ] Section 1 (Hero) - full width, logo visible, text readable
|
||||
- [ ] Section 2 (Choose Your Destiny) - cards display properly
|
||||
- [ ] Section 3 (Why Firefrost) - 3-column grid intact
|
||||
- [ ] Section 4 (Community Awaits) - stats display correctly
|
||||
- [ ] Section 5 (Origin Story) - text formatting preserved
|
||||
- [ ] Footer - all 3 columns, social links visible
|
||||
|
||||
### Activation
|
||||
1. Click Activate in theme preview
|
||||
2. Open incognito window
|
||||
3. Visit firefrostgaming.com and hard refresh
|
||||
|
||||
### Post-Migration Cleanup
|
||||
1. Refactor homepage HTML sections - remove all inline font-size: X !important
|
||||
2. Consolidate CSS in Site Header injection
|
||||
3. Test responsiveness on mobile/tablet
|
||||
|
||||
### Rollback Plan
|
||||
1. Settings → Design & Branding → Change Theme → Upload backed-up Casper fork
|
||||
2. Activate immediately
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Homepage renders identically to current Casper version
|
||||
- [ ] Custom CSS applies without inline !important workarounds
|
||||
- [ ] Typography sizes match design (4rem h2, 2.5rem h3, etc.)
|
||||
- [ ] Full-width layout works without right-shift
|
||||
- [ ] Zero downtime during migration
|
||||
|
||||
## Estimated Time: ~2 hours
|
||||
|
||||
---
|
||||
**Created:** Session 36 (The Chronicler #36)
|
||||
**Status:** PENDING
|
||||
Reference in New Issue
Block a user