firefrost-operations-manual/docs/planning/decap-cms-implementation-plan.md

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)

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

cd ~/firefrost-operations-manual/website-11ty-test/
mkdir -p admin

Step 2: Create Decap Loader (admin/index.html)

<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Firefrost CMS</title>
</head>
<body>
  <script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
</body>
</html>

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

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

# 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

- 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

# 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