CMS Setup Guide

This guide covers setting up the visual content editor for non-technical contributors.

Overview

The documentation site includes a visual CMS (Content Management System) that allows team members to edit content without using Git directly. The CMS is accessible at:

Production: https://team.symphonycore.com/admin/

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User edits    │────▶│   CMS commits   │────▶│ Cloudflare Pages│
│   in browser    │     │   to GitHub     │     │ auto-rebuilds   │
└─────────────────┘     └─────────────────┘     └─────────────────┘

1. User logs in at /admin/ with their GitHub account
2. User edits content using the visual editor
3. CMS automatically commits changes to the master branch
4. Cloudflare Pages detects the commit and rebuilds the site

Initial Setup (One-Time)

Step 1: Create GitHub OAuth App

1. Go to GitHub Developer Settings
2. Click "New OAuth App"
3. Fill in the form:
   • Application name: Symphony Core Docs CMS
   • Homepage URL: https://team.symphonycore.com
   • Authorization callback URL: https://team.symphonycore.com/api/auth/callback
4. Click "Register application"
5. Copy the Client ID
6. Click "Generate a new client secret" and copy the secret

Step 2: Add Secrets to Cloudflare Pages

1. Go to Cloudflare Dashboard
2. Navigate to Pages → internal-docs → Settings → Environment variables
3. Add the following variables for Production:

Variable Name	Value
GITHUB_OAUTH_CLIENT_ID	Your GitHub OAuth Client ID
GITHUB_OAUTH_CLIENT_SECRET	Your GitHub OAuth Client Secret

4. Click Save
5. Trigger a new deployment (or push a commit)

Step 3: Grant Repository Access

Ensure the GitHub OAuth App has access to the symphonycore-org/internal-docs repository:

1. Users who will use the CMS need write access to the repository
2. The OAuth App needs to be authorized for the symphonycore-org organization

Using the CMS

Logging In

1. Navigate to https://team.symphonycore.com/admin/
2. Click "Login with GitHub"
3. Authorize the OAuth App (first time only)
4. You'll see the CMS dashboard

Content Collections

The CMS organizes content into collections:

Collection	Location	Description
Architecture Docs	docs/architecture/	Technical architecture documentation
Training Materials	docs/training/	Training guides and courses
SEO Training	docs/training/seo/searchatlas-top-of-google/	SearchAtlas SEO course
Tools & Resources	docs/tools-and-resources/	Tool guides and workflows
PRDs	docs/prds/	Product requirement documents
Project Management	docs/project-management/	Project documentation
Maintenance	docs/maintenance/	Maintenance and issue tracking
Homepage	docs/index.md	Site homepage content

Creating New Content

1. Select a collection from the left sidebar
2. Click "New [item type]"
3. Fill in the fields:
   • Title (required)
   • Description (optional, used for SEO)
   • Body (the main content)
4. Click "Publish" to save

Editing Existing Content

1. Select a collection
2. Click on the item you want to edit
3. Make your changes
4. Click "Publish" to save

Editor Features

The visual editor supports:

• Rich text formatting: Bold, italic, headings, lists
• Links: Internal and external links
• Images: Upload or link to images
• Code blocks: Syntax-highlighted code
• Tables: Create and edit tables
• Markdown: Switch to raw markdown mode if needed

Troubleshooting

"Unable to login" Error

1. Verify the OAuth App credentials are correct in Cloudflare
2. Check that the callback URL exactly matches: https://team.symphonycore.com/api/auth/callback
3. Ensure you have write access to the repository

Changes Not Appearing

1. Check if the deployment completed in Cloudflare Pages dashboard
2. Clear your browser cache
3. Wait 2-3 minutes for CDN propagation

"Permission denied" Error

1. Ensure your GitHub account has write access to symphonycore-org/internal-docs
2. Re-authorize the OAuth App if needed

Technical Details

Files Added

internal-docs/
├── static/admin/
│   ├── index.html          # CMS entry point
│   └── config.yml          # CMS configuration
└── functions/api/
    ├── auth.js             # OAuth initiation
    └── auth/callback.js    # OAuth callback handler

CMS Technology

• CMS: Sveltia CMS (modern Decap/Netlify CMS alternative)
• Authentication: GitHub OAuth via Cloudflare Functions
• Storage: Git-based (commits directly to repository)

Security

• OAuth tokens are never stored on the server
• Authentication is handled entirely client-side after token exchange
• Only users with repository write access can make changes
• All changes are tracked in Git history

Local Development

To test the CMS locally:

1. Install dependencies:

   npm install

2. Enable local backend in static/admin/config.yml:

   local_backend: true

3. Run the Decap CMS proxy server:

   npx decap-server

4. In another terminal, start Docusaurus:

   npm start

5. Navigate to http://localhost:3000/admin/

Note: Remember to disable local_backend before committing!