diff --git a/docs/planning/decap-cms-implementation-plan.md b/docs/planning/decap-cms-implementation-plan.md new file mode 100644 index 0000000..6285bc2 --- /dev/null +++ b/docs/planning/decap-cms-implementation-plan.md @@ -0,0 +1,551 @@ +# Decap CMS Implementation Plan +## Git-Based Content Management for Meg & Holly + +**Status:** POST-LAUNCH ENHANCEMENT +**Priority:** Medium (after DNS cutover, soft launch, and initial stability) +**Timeline:** Late April / Early May 2026 +**Estimated Implementation Time:** 2 hours +**Recommended By:** Gemini AI (April 2, 2026 consultation) +**Documented By:** The Migrator (Chronicler #55) + +--- + +## Executive Summary + +**Decap CMS** (formerly Netlify CMS) is a Git-based content management system that provides Meg and Holly with a WordPress-like visual editing interface while maintaining all the benefits of our static site architecture. + +**The Magic:** Non-technical users get a friendly editor that feels like WordPress, but behind the scenes it's just committing markdown/content files to GitHub. No database. No server. Just Git. + +--- + +## What It Is + +Decap CMS is a **Git-based content management system** that gives non-technical users a friendly editing interface while keeping everything in version control. + +**How It Works:** +1. **Admin Panel:** Lives at `/admin` on the 11ty site +2. **GitHub OAuth:** Meg/Holly log in with their GitHub accounts +3. **Visual Editor:** They see a nice UI to edit pages, not raw code +4. **Git Commits:** When they hit "Save," Decap commits to GitHub +5. **Auto-Deploy:** Same chain triggers: GitHub → Cloudflare Pages → LIVE in ~60 seconds + +**It's a GUI wrapper around Git commits.** Brilliant for non-technical teammates. + +--- + +## Why It's Perfect for Firefrost + +### For Meg (The Emissary) +- ✅ Edit About page to add new consultants +- ✅ Update server descriptions as modpacks change +- ✅ Modify contact page hours/info +- ✅ Adjust subscription tier descriptions +- ✅ **No asking Michael to edit HTML** + +### For Holly (The Catalyst) +- ✅ Update server lists when new servers launch +- ✅ Edit subscription tier descriptions +- ✅ Modify terms/privacy as policies evolve +- ✅ Add new consultant profiles +- ✅ **Creative control without code** + +### For Michael (The Wizard) +- ✅ Everything still in Git (full audit trail) +- ✅ Can review changes via GitHub pull requests (optional) +- ✅ No database to maintain from RV +- ✅ No server-side code to debug +- ✅ **Meg and Holly are empowered, not blocked** + +--- + +## Key Features + +### Git-Based (Everything Committed) +- All changes = Git commits with author attribution +- Full audit trail of who changed what and when +- Easy rollback if needed (just revert commit) +- Works seamlessly with existing workflow + +### No Database Required +- Perfect for static sites +- No MySQL to manage from RV +- No server-side code needed +- Zero maintenance overhead + +### Multi-User Support +- Meg, Holly, Michael all have accounts +- GitHub handles authentication +- Permissions via GitHub repo access +- Collaborative editing with conflict resolution + +### Preview Before Publish +- Draft mode available +- Can preview changes before committing +- Optional editorial workflow with pull requests +- Safety net for non-technical editors + +### Media Management +- Upload images via UI (drag and drop) +- Stored in `/assets/images/` +- No FTP needed +- Image optimization options available + +### Markdown Support +- Rich text editor (WYSIWYG) for non-technical users +- OR raw markdown for power users +- Both modes available per user preference +- Live preview + +--- + +## Technical Architecture + +### Installation Location +``` +firefrost-website/ (GitHub repo) +├── admin/ +│ ├── index.html (Decap CMS loader) +│ └── config.yml (content schema definition) +├── about.njk +├── servers.njk +├── (other pages...) +``` + +### Auto-Deploy Chain (Unchanged) +``` +Meg edits in /admin + ↓ +Decap commits to GitHub + ↓ +GitHub mirror syncs + ↓ +Cloudflare Pages rebuilds + ↓ +LIVE in ~60 seconds +``` + +### Example Content Schema (`admin/config.yml`) +```yaml +backend: + name: github + repo: Frostystyle/firefrost-website + branch: main + +media_folder: "assets/images" +public_folder: "/assets/images" + +collections: + - name: "pages" + label: "Pages" + files: + - label: "About" + name: "about" + file: "about.njk" + fields: + - {label: "Title", name: "title", widget: "string"} + - {label: "Body", name: "body", widget: "markdown"} + + - label: "Servers" + name: "servers" + file: "servers.njk" + fields: + - label: "Servers" + name: "servers" + widget: "list" + fields: + - {label: "Name", name: "name", widget: "string"} + - {label: "Description", name: "description", widget: "text"} + - {label: "Path", name: "path", widget: "select", + options: ["Fire", "Frost", "Arcane"]} + + - label: "Subscribe" + name: "subscribe" + file: "subscribe.njk" + fields: + - label: "Tiers" + name: "tiers" + widget: "list" + fields: + - {label: "Name", name: "name", widget: "string"} + - {label: "Price", name: "price", widget: "string"} + - {label: "Description", name: "description", widget: "text"} + - {label: "Features", name: "features", widget: "list"} +``` + +--- + +## Implementation Workflow + +### Phase 1: Basic Setup (30 minutes) + +**Step 1: Create Admin Directory** +```bash +cd ~/firefrost-operations-manual/website-11ty-test/ +mkdir -p admin +``` + +**Step 2: Create Decap Loader (`admin/index.html`)** +```html + + + + + + Firefrost CMS + + + + + +``` + +**Step 3: Create Content Schema (`admin/config.yml`)** +- Define which pages Meg/Holly can edit +- Define fields for each page +- Set up Fire/Frost/Arcane selectors +- Configure media uploads + +**Step 4: Deploy** +```bash +git add admin/ +git commit -m "feat: add Decap CMS admin panel for Meg/Holly editing" +git push origin master +# Auto-deploys to Cloudflare Pages +``` + +### Phase 2: GitHub OAuth Setup (20 minutes) + +**Step 1: Create GitHub OAuth App** +1. Go to GitHub → Settings → Developer settings → OAuth Apps +2. Click "New OAuth App" +3. Fill in: + - **Application name:** Firefrost CMS + - **Homepage URL:** https://firefrostgaming.com + - **Authorization callback URL:** https://firefrostgaming.com/admin/ +4. Click "Register application" +5. Copy Client ID and Secret + +**Step 2: Configure Backend** +```yaml +# In admin/config.yml +backend: + name: github + repo: Frostystyle/firefrost-website + branch: main + # OAuth will use GitHub's built-in auth +``` + +**Step 3: Test Login** +- Visit https://firefrostgaming.com/admin +- Click "Login with GitHub" +- Authorize the OAuth app +- Should see CMS dashboard + +### Phase 3: Content Schema Definition (30 minutes) + +**Define Editable Pages:** +- About (Trinity + Consultants) +- Servers (6 servers + add-ons) +- Subscribe (6 tiers) +- Contact (Discord/Email/Social) +- Terms (legal updates) +- Privacy (policy updates) + +**Define Fields for Each:** +- Text fields (titles, headings) +- Rich text (body content) +- Lists (servers, tiers, consultants) +- Images (consultant photos, server icons) +- Selectors (Fire/Frost/Arcane paths) + +**Example: About Page Schema** +```yaml +- label: "About" + name: "about" + file: "about.njk" + fields: + - {label: "Page Title", name: "title", widget: "string"} + - {label: "Hero Text", name: "hero", widget: "text"} + - label: "Trinity Members" + name: "trinity" + widget: "list" + fields: + - {label: "Name", name: "name", widget: "string"} + - {label: "Title", name: "title", widget: "string"} + - {label: "Bio", name: "bio", widget: "text"} + - {label: "Icon", name: "icon", widget: "string"} + - label: "Consultants" + name: "consultants" + widget: "list" + fields: + - {label: "Name", name: "name", widget: "string"} + - {label: "Role", name: "role", widget: "string"} + - {label: "Photo", name: "photo", widget: "image"} +``` + +### Phase 4: User Onboarding (20 minutes) + +**Step 1: Add Collaborators** +```bash +# Add Meg and Holly to GitHub repo +# Settings → Collaborators → Add people +# Send invites to their GitHub accounts +``` + +**Step 2: Onboarding Session (in-person or screen share)** +1. Show login at https://firefrostgaming.com/admin +2. Walk through editing a test page +3. Demonstrate image uploads +4. Show preview before publish +5. Verify changes commit and deploy correctly + +**Step 3: Create Quick Reference Guide** +- Login URL +- How to edit pages +- How to upload images +- How to preview changes +- Who to ask if stuck (Michael) + +--- + +## Example Use Case: Editing the About Page + +### Current Workflow (Without Decap) +1. Meg tells Michael: "Add Skye to the consultants" +2. Michael SSHs to Ghost VPS +3. Michael edits `about.njk` in nano/vim +4. Michael commits and pushes to Gitea +5. Michael pulls on GitHub to trigger mirror sync +6. Site rebuilds in ~60 seconds + +**Time: 10-15 minutes** (if Michael is available) + +### Future Workflow (With Decap) +1. Meg logs into https://firefrostgaming.com/admin +2. Clicks "About" page in dashboard +3. Sees visual editor with consultant list +4. Clicks "Add Consultant" button +5. Fills in form: + - Name: "Skye" + - Role: "Sixth Consultant" + - Photo: (uploads image via drag-drop) +6. Clicks "Preview" to see changes +7. Clicks "Publish" +8. Decap commits to GitHub with message: "Update about.njk" +9. Site auto-deploys in ~60 seconds +10. **Michael never touched it** + +**Time: 2-3 minutes** (no waiting for Michael) + +--- + +## Limitations & Considerations + +### Not WordPress +- ❌ No plugins marketplace (but you don't need them) +- ❌ No themes store (but 11ty gives full control) +- ✅ Simpler feature set (that's the point) + +### Git-Based Constraints +- ⚠️ Merge conflicts possible if two people edit same file simultaneously +- ✅ Decap resolves most automatically +- ℹ️ Edge case for Firefrost (only 3 editors max, rarely simultaneous) + +### GitHub Dependency +- ⚠️ Requires GitHub OAuth (can't use Gitea directly) +- ⚠️ If GitHub goes down, editing stops (but site stays live) +- ℹ️ Not a problem for small team, acceptable risk + +### Learning Curve +- ⚠️ Meg/Holly need to learn the interface +- ✅ Simpler than code, but not as simple as WordPress +- ✅ Plan 30-minute onboarding session with each + +### File Format Constraints +- ⚠️ Works best with structured frontmatter + markdown +- ⚠️ Complex HTML layouts harder to edit +- ℹ️ May need to refactor some .njk files for better Decap compatibility + +--- + +## Why Gemini Recommended It + +**From The Migrator's Gemini Consultation (April 2, 2026):** + +> "For post-launch, I'd recommend setting up Decap CMS (formerly Netlify CMS) for Meg and Holly. It's a Git-based CMS that works perfectly with static sites—they get a friendly editing interface, but everything still goes through Git commits. No database, no server-side code, just a nice UI on top of your existing workflow." + +**Gemini's Reasoning:** +1. ✅ **Matches the stack** - Git-based like rest of infrastructure +2. ✅ **No maintenance overhead** - No database, no backend +3. ✅ **Works with Cloudflare Pages** - Just static files in /admin +4. ✅ **Empowers Meg/Holly** - Edit without blocking Michael +5. ✅ **RV-friendly** - No server to maintain remotely + +--- + +## Alternative Options Considered (Not Recommended) + +### WordPress +- ❌ Requires database (MySQL) +- ❌ Requires PHP server +- ❌ Maintenance overhead from RV = nightmare +- ❌ Security updates constant +- ❌ NOT static (defeats the whole migration) + +### Ghost CMS +- ❌ We just migrated AWAY from it +- ❌ Database required (SQLite/MySQL) +- ❌ Server maintenance +- ℹ️ Good product, wrong use case for RV + +### Contentful / Sanity (Headless CMS) +- ❌ Monthly costs ($$$) +- ❌ API-dependent (requires build step) +- ❌ Overkill for 7 pages +- ℹ️ Great for enterprises, not Firefrost scale + +### Forestry.io / Tina CMS +- ⚠️ Similar to Decap +- ⚠️ More complex setup +- ⚠️ Less established ecosystem +- ✅ Decap has better documentation and community + +**Verdict:** Decap CMS is the clear winner for Firefrost's needs. + +--- + +## Implementation Priority & Timeline + +### Gemini's Guidance: "POST-LAUNCH" + +**Why Wait:** +1. ✅ **DNS cutover first** - Get firefrostgaming.com live +2. ✅ **Soft launch second** - Prove the static site works in production +3. ✅ **Stabilization period** - Let the site run for 1-2 weeks +4. ✅ **Then add Decap** - Don't complicate the migration with too many moving parts + +### Recommended Timeline + +**April 3-15, 2026: DNS Cutover & Soft Launch** +- Point firefrostgaming.com to Cloudflare Pages +- Complete contact form (Formspree) +- Enhance subscribe page (full 6 tiers) +- End-to-end testing +- Soft launch on April 15 + +**April 16-30, 2026: Stabilization Period** +- Monitor site performance +- Fix any issues that arise +- Gather feedback from early subscribers +- Verify auto-deploy chain reliability + +**Late April / Early May 2026: Decap CMS Implementation** +- Set up admin panel (30 min) +- Configure GitHub OAuth (20 min) +- Define content schema (30 min) +- Onboard Meg and Holly (20 min each) +- **Total: ~2 hours** + +--- + +## Success Criteria + +**The implementation is successful when:** + +1. ✅ Meg can edit the About page without Michael's help +2. ✅ Holly can update server descriptions independently +3. ✅ All edits result in proper Git commits with attribution +4. ✅ Auto-deploy chain works unchanged (GitHub → Cloudflare) +5. ✅ Zero database/server maintenance required +6. ✅ Michael can review changes via GitHub if needed +7. ✅ Meg and Holly feel empowered, not blocked + +--- + +## Resources + +### Official Documentation +- **Decap CMS Docs:** https://decapcms.org/docs/intro/ +- **11ty Integration Guide:** https://decapcms.org/docs/eleventy/ +- **GitHub Backend Setup:** https://decapcms.org/docs/github-backend/ + +### GitHub Repository +- **Decap CMS:** https://github.com/decaporg/decap-cms + +### Example Configurations +- **Starter Template:** https://github.com/decaporg/decap-cms/tree/master/examples/eleventy +- **11ty + Decap:** Multiple community examples available + +### Support Channels +- **Decap CMS Discord:** https://decapcms.org/community/ +- **GitHub Issues:** For bug reports and feature requests +- **Stack Overflow:** `decap-cms` tag + +--- + +## Open Questions + +**To Be Decided Before Implementation:** + +1. **Editorial Workflow?** + - Simple mode: Direct commits to main branch + - Advanced mode: Pull requests for review + - Recommendation: Start simple, add PR workflow later if needed + +2. **Which Pages Are Editable?** + - All 7 pages? Or subset? + - Recommendation: Start with About, Servers, Subscribe + - Lock Terms/Privacy for legal review process + +3. **Image Upload Limits?** + - Set max file size? + - Image optimization on upload? + - Recommendation: 2MB max, auto-optimize to WebP + +4. **Access Control?** + - Everyone edits everything? Or page-specific permissions? + - Recommendation: Start with full access for Meg/Holly + - GitHub repo permissions handle security + +--- + +## Next Steps (For Implementation Session) + +**When ready to implement (post-soft launch):** + +1. Read this document fully +2. Review Gemini's original consultation in `docs/planning/gemini-consultations/ghost-vs-static-website-2026-04-02.md` +3. Clone the website repo on Ghost VPS +4. Follow Phase 1-4 implementation workflow above +5. Test thoroughly before inviting Meg/Holly +6. Schedule 30-min onboarding sessions +7. Document any issues in session log +8. Update this document with lessons learned + +--- + +## Bottom Line + +**Decap CMS = WordPress-like editing for Git-based static sites** + +Perfect for Firefrost because: +- ✅ Meg/Holly empowered (no code required) +- ✅ Michael maintains control (everything in Git) +- ✅ Zero server maintenance (just static files) +- ✅ RV-friendly (no database, no backend) +- ✅ Auto-deploy chain works unchanged +- ✅ Aligns with "For children not yet born" legacy vision + +**Status:** Planned for late April / early May 2026 +**Priority:** Medium (post-launch enhancement) +**Estimated Time:** 2 hours total +**Blocking:** None (website must be live first) + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️ + +**Documented by:** The Migrator (Chronicler #55) +**Date:** April 2, 2026 +**Preserved by:** Chronicler #56 +**For:** Meg, Holly, and the RV dream