zhongwei/gh-jezweb-claude-skills-skills-sveltia-cms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:25:30 +08:00
commit cc481ebf7e
18 changed files with 3271 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "sveltia-cms",
"description": "Set up Sveltia CMS - the lightweight Git-backed CMS successor to Decap/Netlify CMS with 5x smaller bundle (300 KB), GraphQL performance, and 260+ fixed predecessor issues. Framework-agnostic for Hugo, Jekyll, 11ty, Gatsby, Astro. Use when: adding CMS to static sites, migrating from Decap/Netlify CMS, enabling non-technical editors, or troubleshooting OAuth authentication failures, YAML parse errors, CORS/COOP policy problems, content not listing issues.",
"version": "1.0.0",
"author": {
"name": "Jeremy Dawes",
"email": "jeremy@jezweb.net"
},
"skills": [
"./"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# sveltia-cms
Set up Sveltia CMS - the lightweight Git-backed CMS successor to Decap/Netlify CMS with 5x smaller bundle (300 KB), GraphQL performance, and 260+ fixed predecessor issues. Framework-agnostic for Hugo, Jekyll, 11ty, Gatsby, Astro. Use when: adding CMS to static sites, migrating from Decap/Netlify CMS, enabling non-technical editors, or troubleshooting OAuth authentication failures, YAML parse errors, CORS/COOP policy problems, content not listing issues.

1901
SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff

101
plugin.lock.json Normal file
View File

@@ -0,0 +1,101 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:jezweb/claude-skills:skills/sveltia-cms",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "e01595e826385a0fd25849ed6aed6166d2ce6d2e",
"treeHash": "edf718d43cb7f1a316dad0ab54990a53e8bce44cba1a49b9de7c3d14efef490c",
"generatedAt": "2025-11-28T10:19:03.737459Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "sveltia-cms",
"description": "Set up Sveltia CMS - the lightweight Git-backed CMS successor to Decap/Netlify CMS with 5x smaller bundle (300 KB), GraphQL performance, and 260+ fixed predecessor issues. Framework-agnostic for Hugo, Jekyll, 11ty, Gatsby, Astro. Use when: adding CMS to static sites, migrating from Decap/Netlify CMS, enabling non-technical editors, or troubleshooting OAuth authentication failures, YAML parse errors, CORS/COOP policy problems, content not listing issues.",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "834b866091ce5e32bb9d00cc89e8dd779070a1ce1a9583b7dd4419fcfe2d88c4"
},
{
"path": "SKILL.md",
"sha256": "8afec40d79f8871d36879dda88d3c0fa56a4ca94b741d5482a77edd91d8aeec7"
},
{
"path": "references/migration-from-decap.md",
"sha256": "30cfd4339257ff5938b5a7d167fe38b48f72d3b53878cb8f9daef6236f3b795d"
},
{
"path": "scripts/check-versions.sh",
"sha256": "2756fa607b4f01af4475970059994d83ebdc9eda8667a45b363a1f2efcb71c47"
},
{
"path": "scripts/init-sveltia.sh",
"sha256": "08708a13c15e676f137485f6bc6de46bc979efb314fb69154aee8ed5d223734c"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "38ad7f49dac13aecf18ebbc0c98c38280f051e3ec6eae2f854bd8c31537cf1c9"
},
{
"path": "templates/jekyll/index.html",
"sha256": "7306457ecf393d830949a86f552ed83c4558ee442563ba64dc22f10e9c94909b"
},
{
"path": "templates/jekyll/config.yml",
"sha256": "838897fad8f8a4a7ff949f734f32c7652509fc937bd27fc214ac12ecd395872f"
},
{
"path": "templates/hugo/index.html",
"sha256": "7306457ecf393d830949a86f552ed83c4558ee442563ba64dc22f10e9c94909b"
},
{
"path": "templates/hugo/config.yml",
"sha256": "edfef1b22a10496fad144afa210af8900cf354999a6011cc56f9432c0f2fccd3"
},
{
"path": "templates/11ty/index.html",
"sha256": "7306457ecf393d830949a86f552ed83c4558ee442563ba64dc22f10e9c94909b"
},
{
"path": "templates/11ty/config.yml",
"sha256": "3b13f466b1a440a7f196cc22df86ea14341a493763724f4d14b3f343d6d6a1af"
},
{
"path": "templates/cloudflare-workers/wrangler.jsonc",
"sha256": "a545a8f5e83d052622356f7a7272ba0976a829d27b3e9bf482283743c39457c8"
},
{
"path": "templates/cloudflare-workers/setup-guide.md",
"sha256": "85d4755dbc25ce2dffc3d8fc518927f4e8f813190992e12ef9741c8d96010c9b"
},
{
"path": "templates/collections/blog-posts.yml",
"sha256": "3114fcf67d00f00aaea3bd6ce3ea7803509f1014b262ce4ec7d6b5172d1c0cf0"
},
{
"path": "templates/collections/landing-pages.yml",
"sha256": "0fa851c8ab3d960929135e363ee7c828fb41a88c122bbea8aed20d8b396de049"
},
{
"path": "templates/collections/docs-pages.yml",
"sha256": "d4748695e3c8a8b956828483238fa8adedc68630c04d8ccebe4747b87b13adcb"
}
],
"dirSha256": "edf718d43cb7f1a316dad0ab54990a53e8bce44cba1a49b9de7c3d14efef490c"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

241
references/migration-from-decap.md Normal file
View File

@@ -0,0 +1,241 @@
# Migrating from Decap CMS to Sveltia CMS
**TL;DR**: Change 1 line in `admin/index.html`. Your config.yml works as-is.
---
## Why Migrate?
**Sveltia CMS** is the modern successor to Decap CMS (formerly Netlify CMS) with:
- ✅ **5x smaller bundle** (300 KB vs 1.5 MB)
- ✅ **Faster performance** (GraphQL, instant loading)
- ✅ **260+ issues solved** from Decap CMS
- ✅ **Better mobile support**
- ✅ **Dark mode** built-in
- ✅ **Active maintenance** (frequent releases)
- ✅ **100% config compatible**
---
## Migration Steps
### Step 1: Update Script Tag
**Location**: `static/admin/index.html` (Hugo) or `admin/index.html` (Jekyll/11ty)
**OLD (Decap CMS)**:
```html
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
```
**NEW (Sveltia CMS)**:
```html
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
```
**Important**: Add `type="module"` attribute!
---
### Step 2: Keep Existing Config
```yaml
# admin/config.yml - NO CHANGES NEEDED!
backend:
name: github
repo: owner/repo
branch: main
# base_url: ... (keep if using OAuth proxy)
media_folder: static/images
public_folder: /images
collections:
# ... all your existing collections work as-is
```
**Your entire config.yml is 100% compatible!**
---
### Step 3: Test Locally
```bash
# Start your site's dev server
hugo server # or jekyll serve, or npm run dev
# Visit admin
open http://localhost:1313/admin/ # (or your port)
```
**Test these workflows**:
- ✅ Login (should work with existing OAuth)
- ✅ View content list
- ✅ Edit existing entry
- ✅ Create new entry
- ✅ Upload image
- ✅ Save and publish
---
### Step 4: Deploy
```bash
git add static/admin/index.html # or your admin path
git commit -m "Migrate to Sveltia CMS from Decap CMS"
git push
```
**That's it!** Your site rebuilds with Sveltia CMS.
---
## What Changes?
### UI Changes (Better UX)
- **Performance**: Instant content loading (GraphQL)
- **Search**: Full-text search across all content
- **Mobile**: Better mobile and tablet experience
- **Dark Mode**: Automatic dark mode support
- **Image Optimization**: Built-in WebP conversion
### What Stays the Same
- **Content**: All your Markdown/JSON/YAML files unchanged
- **Collections**: Same collection definitions
- **Fields**: Same field widgets and validation
- **Workflows**: Same editorial workflow
- **Media**: Same media folder and uploads
---
## What's Not Supported?
Sveltia CMS deliberately omits these Decap features for performance:
- ❌ **Git Gateway backend** (use OAuth proxy instead)
- ❌ **Azure backend** (may be added later)
- ❌ **Bitbucket backend** (may be added later)
**If you use Git Gateway**, switch to **Cloudflare Workers OAuth** (faster, more reliable):
- See: `templates/cloudflare-workers/setup-guide.md`
- Takes 10 minutes to set up
- Free tier: 100k requests/day
---
## Testing Checklist
Before fully migrating, verify these work:
- [ ] Login with OAuth
- [ ] View all collections
- [ ] Edit existing content
- [ ] Create new content
- [ ] Upload images
- [ ] Publish/unpublish works
- [ ] Search functionality
- [ ] Mobile editing (if applicable)
- [ ] i18n switching (if applicable)
---
## Rollback Plan
If you need to rollback:
1. **Revert script tag** to Decap CMS:
```html
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
```
2. **Commit and push**:
```bash
git add static/admin/index.html
git commit -m "Rollback to Decap CMS"
git push
```
**Your content and config are unchanged** - you can switch back and forth freely!
---
## Common Migration Issues
### Issue: "SVELTIA is not defined"
**Cause**: Missing `type="module"` attribute
**Fix**:
```html
<!-- Correct -->
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
<!-- Wrong - missing type="module" -->
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
```
---
### Issue: OAuth Not Working
**Cause**: Using Git Gateway (not supported)
**Fix**: Switch to Cloudflare Workers OAuth:
1. Deploy OAuth Worker (5 min)
2. Update config.yml with `base_url`
3. Test authentication
See: `templates/cloudflare-workers/setup-guide.md`
---
### Issue: TOML Files Not Loading
**Cause**: Sveltia's TOML support is buggy in beta
**Fix**: Use YAML instead:
```yaml
collections:
- name: posts
folder: content/posts
format: yaml # Change from: toml
```
Or wait for TOML fixes in future releases.
---
## Performance Comparison
| Metric | Decap CMS | Sveltia CMS | Improvement |
|--------|-----------|-------------|-------------|
| **Bundle Size** | 1.5 MB | 300 KB | **5x smaller** |
| **Initial Load** | 2-3 sec | 0.5-1 sec | **3x faster** |
| **Content Listing** | Sequential API calls | Single GraphQL query | **10x faster** |
| **Search** | Client-side only | Full-text | **Much better** |
| **Mobile UX** | Poor | Good | **Significantly improved** |
---
## Support & Help
**Issues after migration?**
- GitHub: https://github.com/sveltia/sveltia-cms/issues
- Discussions: https://github.com/sveltia/sveltia-cms/discussions
**Questions about Decap compatibility?**
- Sveltia maintainer is very responsive
- Most Decap configs work without changes
---
**Migration Time**: 5-10 minutes
**Risk Level**: Very Low (config unchanged, easy rollback)
**Recommended**: Yes (significant improvements)
---
**Last Updated**: 2025-10-24

33
scripts/check-versions.sh Executable file
View File

@@ -0,0 +1,33 @@
#!/usr/bin/env bash
# Check Sveltia CMS version and compatibility
set -e
echo "🔍 Checking Sveltia CMS versions..."
echo ""
# Check npm package version
echo "📦 Latest npm package:"
npm view @sveltia/cms version
echo ""
echo "📅 Last published:"
npm view @sveltia/cms time.modified
echo ""
echo "🏷️ Current skill version: 0.113.3"
echo ""
# Check if newer version available
CURRENT="0.113.3"
LATEST=$(npm view @sveltia/cms version)
if [ "$CURRENT" != "$LATEST" ]; then
echo "⚠️ WARNING: Newer version available ($LATEST)"
echo " Consider updating skill metadata"
else
echo "✅ Skill is up to date"
fi
echo ""

138
scripts/init-sveltia.sh Executable file
View File

@@ -0,0 +1,138 @@
#!/usr/bin/env bash
# Sveltia CMS Initialization Script
# Automates setup for Hugo, Jekyll, or 11ty projects
set -e
echo "🚀 Sveltia CMS Setup"
echo "===================="
echo ""
# Detect framework
detect_framework() {
if [ -f "config.toml" ] || [ -f "config.yaml" ] || [ -f "hugo.toml" ]; then
echo "hugo"
elif [ -f "_config.yml" ] || [ -f "Gemfile" ]; then
echo "jekyll"
elif [ -f ".eleventy.js" ] || [ -f "eleventy.config.js" ]; then
echo "11ty"
elif [ -f "astro.config.mjs" ]; then
echo "astro"
else
echo "unknown"
fi
}
FRAMEWORK=$(detect_framework)
echo "📦 Detected framework: $FRAMEWORK"
echo ""
# Set admin directory based on framework
case $FRAMEWORK in
hugo)
ADMIN_DIR="static/admin"
;;
jekyll)
ADMIN_DIR="admin"
;;
11ty)
ADMIN_DIR="admin"
;;
astro)
ADMIN_DIR="public/admin"
;;
*)
read -p "❓ Admin directory path (e.g., static/admin): " ADMIN_DIR
;;
esac
echo "📁 Creating admin directory: $ADMIN_DIR"
mkdir -p "$ADMIN_DIR"
# Create index.html
echo "📄 Creating index.html..."
cat > "$ADMIN_DIR/index.html" << 'EOF'
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Content Manager</title>
</head>
<body>
<!-- Sveltia CMS -->
<script src="https://unpkg.com/@sveltia/cms@0.113.3/dist/sveltia-cms.js" type="module"></script>
</body>
</html>
EOF
# Get repository info
echo ""
read -p "📝 GitHub repository (e.g., owner/repo): " REPO
read -p "🌿 Default branch (default: main): " BRANCH
BRANCH=${BRANCH:-main}
# Create config.yml
echo "⚙️ Creating config.yml..."
cat > "$ADMIN_DIR/config.yml" << EOF
backend:
name: github
repo: $REPO
branch: $BRANCH
# base_url: https://your-worker.workers.dev # Add your OAuth proxy URL
# Media storage
media_folder: static/images/uploads # Adjust for your framework
public_folder: /images/uploads
# Optional: Image optimization
media_libraries:
default:
config:
max_file_size: 5242880 # 5 MB
slugify_filename: true
transformations:
raster_image:
format: webp
quality: 85
width: 2048
height: 2048
# Collections
collections:
- name: posts
label: Blog Posts
folder: content/posts # Adjust for your framework
create: true
slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
format: yaml
fields:
- { label: Title, name: title, widget: string }
- { label: Date, name: date, widget: datetime }
- { label: Draft, name: draft, widget: boolean, default: true }
- { label: Body, name: body, widget: markdown }
EOF
echo ""
echo "✅ Sveltia CMS setup complete!"
echo ""
echo "📋 Next steps:"
echo " 1. Review and customize: $ADMIN_DIR/config.yml"
echo " 2. Set up OAuth (see: templates/cloudflare-workers/setup-guide.md)"
echo " 3. Start your dev server and visit /admin/"
echo ""
if [ "$FRAMEWORK" = "jekyll" ]; then
echo "⚠️ Jekyll users: Add to _config.yml:"
echo " include:"
echo " - admin"
echo ""
fi
if [ "$FRAMEWORK" = "11ty" ]; then
echo "⚠️ 11ty users: Add to .eleventy.js:"
echo " eleventyConfig.addPassthroughCopy('admin');"
echo ""
fi

63
templates/11ty/config.yml Normal file
View File

@@ -0,0 +1,63 @@
# Sveltia CMS Configuration for 11ty (Eleventy)
# Place this file in: admin/config.yml
backend:
name: github
repo: owner/repo # Change to your GitHub repository
branch: main
base_url: https://your-worker.workers.dev # Your Cloudflare Workers OAuth proxy URL
# Media storage
media_folder: src/assets/images
public_folder: /assets/images
# Optional: Image optimization
media_libraries:
default:
config:
max_file_size: 5242880
slugify_filename: true
transformations:
raster_image:
format: webp
quality: 85
width: 2048
height: 2048
# Collections
collections:
# Blog Posts
- name: blog
label: Blog Posts
folder: src/posts
create: true
slug: '{{slug}}'
fields:
- label: Title
name: title
widget: string
- label: Description
name: description
widget: text
required: false
- label: Date
name: date
widget: datetime
date_format: 'YYYY-MM-DD'
time_format: false
- label: Tags
name: tags
widget: list
required: false
- label: Featured Image
name: image
widget: image
required: false
- label: Body
name: body
widget: markdown

12
templates/11ty/index.html Normal file
View File

@@ -0,0 +1,12 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Content Manager</title>
</head>
<body>
<!-- Sveltia CMS -->
<script src="https://unpkg.com/@sveltia/cms@0.113.3/dist/sveltia-cms.js" type="module"></script>
</body>
</html>

347
templates/cloudflare-workers/setup-guide.md Normal file
View File

@@ -0,0 +1,347 @@
# Cloudflare Workers OAuth Proxy Setup
Complete guide to deploying Sveltia CMS authentication using Cloudflare Workers.
---
## Overview
This OAuth proxy enables Sveltia CMS to authenticate with GitHub or GitLab without requiring a backend server. The Worker handles the OAuth flow securely.
**Official Repository**: https://github.com/sveltia/sveltia-cms-auth
---
## Prerequisites
- Cloudflare account (free tier works)
- GitHub or GitLab account
- Wrangler CLI installed (`npm install -g wrangler`)
- Git repository with Sveltia CMS
---
## Step 1: Deploy the Worker
### Option A: Use Official Repository (Recommended)
```bash
# Clone the official auth worker
git clone https://github.com/sveltia/sveltia-cms-auth
cd sveltia-cms-auth
# Install dependencies
npm install
# Login to Cloudflare (if not already logged in)
npx wrangler login
# Deploy to Workers
npx wrangler deploy
```
**Output**:
```
⛅️ wrangler 3.x.x
-------------------
Uploaded sveltia-cms-auth (x.x KiB)
Published sveltia-cms-auth (x.xx sec)
https://sveltia-cms-auth.<your-subdomain>.workers.dev
```
**Save this URL** - you'll need it later!
---
### Option B: One-Click Deploy
1. Visit https://github.com/sveltia/sveltia-cms-auth
2. Click the "Deploy to Cloudflare Workers" button
3. Follow the deployment wizard
4. Note the deployed Worker URL
---
### Option C: Use This Template
If you want to customize the Worker:
1. Copy template to your project:
```bash
mkdir -p workers/sveltia-auth
cp templates/cloudflare-workers/* workers/sveltia-auth/
```
2. Update `wrangler.jsonc` with your account ID
3. Deploy:
```bash
cd workers/sveltia-auth
npx wrangler deploy
```
---
## Step 2: Register OAuth App on GitHub
1. **Go to GitHub Settings:**
https://github.com/settings/developers
2. **Click "New OAuth App"**
3. **Fill in details:**
- **Application name**: `Your Site CMS` (or any name)
- **Homepage URL**: `https://yourdomain.com` (your actual site)
- **Authorization callback URL**: `https://sveltia-cms-auth.<your-subdomain>.workers.dev/callback`
- ⚠️ **Critical**: This must be the Worker URL + `/callback`
- ❌ **NOT**: `https://yourdomain.com/callback`
- ✅ **Example**: `https://sveltia-cms-auth.my-account.workers.dev/callback`
4. **Click "Register application"**
5. **Save these values:**
- **Client ID**: `Ov23li...` (visible immediately)
- **Client Secret**: Click "Generate a new client secret" and copy it (shown once!)
---
## Step 3: Configure Worker Environment Variables
Set the secrets using Wrangler CLI:
```bash
cd sveltia-cms-auth # or your Worker directory
# Set GitHub Client ID
npx wrangler secret put GITHUB_CLIENT_ID
# Paste your Client ID when prompted
# Set GitHub Client Secret
npx wrangler secret put GITHUB_CLIENT_SECRET
# Paste your Client Secret when prompted
```
**Optional**: Restrict to specific domains:
```bash
npx wrangler secret put ALLOWED_DOMAINS
# Enter domains when prompted, e.g.: yourdomain.com,*.yourdomain.com
```
**Wildcards**:
- `yourdomain.com` - Exact match only
- `*.yourdomain.com` - All subdomains (www.yourdomain.com, blog.yourdomain.com)
- `yourdomain.com,*.yourdomain.com` - Both root and subdomains
---
## Step 4: Update Sveltia CMS Config
Add the `base_url` to your CMS configuration:
```yaml
# static/admin/config.yml (Hugo)
# or admin/config.yml (Jekyll/11ty)
# or public/admin/config.yml (Astro/Next.js)
backend:
name: github
repo: owner/repo # Your GitHub repository
branch: main # Your default branch
base_url: https://sveltia-cms-auth.<your-subdomain>.workers.dev # ← Add this line
```
**Example**:
```yaml
backend:
name: github
repo: jezweb/my-blog
branch: main
base_url: https://sveltia-cms-auth.my-account.workers.dev
```
---
## Step 5: Test Authentication
1. **Start your local dev server:**
```bash
hugo server # or jekyll serve, or npm run dev
```
2. **Open admin in browser:**
```
http://localhost:1313/admin/ # Hugo
http://localhost:4000/admin/ # Jekyll
http://localhost:8080/admin/ # 11ty
http://localhost:4321/admin/ # Astro
```
3. **Click "Login with GitHub"**
4. **Authorize the app** when GitHub asks
5. **You should be redirected back** to the CMS with content loaded
---
## Step 6: Deploy Your Site
1. **Commit changes:**
```bash
git add static/admin/config.yml # or your admin path
git commit -m "Add Cloudflare Workers OAuth for Sveltia CMS"
git push
```
2. **Deploy to your hosting:**
- Cloudflare Pages: Automatic on push
- Vercel: Automatic on push
- Netlify: Automatic on push
- GitHub Pages: GitHub Actions workflow
3. **Test on production:**
```
https://yourdomain.com/admin/
```
---
## GitLab Setup (Alternative)
If using GitLab instead of GitHub:
### 1. Create GitLab Application
1. Go to https://gitlab.com/-/profile/applications
2. Click "Add new application"
3. Fill in:
- **Name**: `Your Site CMS`
- **Redirect URI**: `https://sveltia-cms-auth.<your-subdomain>.workers.dev/callback`
- **Scopes**: Check `api` and `write_repository`
4. Click "Save application"
5. Copy Application ID and Secret
### 2. Set Worker Secrets
```bash
npx wrangler secret put GITLAB_APPLICATION_ID
# Paste Application ID
npx wrangler secret put GITLAB_SECRET
# Paste Secret
```
### 3. Update CMS Config
```yaml
backend:
name: gitlab
repo: group/project
branch: main
base_url: https://sveltia-cms-auth.<your-subdomain>.workers.dev
```
---
## Troubleshooting
### Authentication Fails
**Problem**: "Error: Failed to authenticate"
**Solutions**:
1. Check callback URL matches exactly (Worker URL + `/callback`)
2. Verify secrets are set: `npx wrangler secret list`
3. Test Worker directly: `curl https://your-worker.workers.dev/health`
4. Check browser console for CORS errors
---
### Redirect to Wrong Domain
**Problem**: Redirects to `api.netlify.com/auth`
**Solutions**:
1. Ensure `base_url` is in config.yml
2. Hard refresh browser (Ctrl+Shift+R)
3. Clear browser cache
---
### CORS Errors
**Problem**: "Cross-Origin-Opener-Policy blocked"
**Solutions**:
1. Add COOP header to site (see SKILL.md Error #8)
2. Set `Cross-Origin-Opener-Policy: same-origin-allow-popups`
3. For Cloudflare Pages, add `_headers` file:
```
/*
Cross-Origin-Opener-Policy: same-origin-allow-popups
```
---
### Worker Not Found (404)
**Problem**: Worker URL returns 404
**Solutions**:
1. Verify deployment: `npx wrangler deployments list`
2. Check Worker name in `wrangler.jsonc`
3. Wait 1-2 minutes after deployment (DNS propagation)
---
## Security Best Practices
1. **Never commit secrets** - Use `npx wrangler secret put`
2. **Restrict domains** - Set `ALLOWED_DOMAINS` for production
3. **Use HTTPS only** - Sveltia CMS requires secure context
4. **Rotate secrets periodically** - Update GitHub OAuth secrets every 6-12 months
5. **Monitor access logs** - Check Cloudflare Workers dashboard for unusual activity
---
## Custom Domain (Optional)
To use a custom domain for your OAuth Worker:
1. **Add Worker route in Cloudflare:**
- Dashboard > Workers > Your Worker > Triggers
- Add custom domain: `auth.yourdomain.com`
2. **Update GitHub OAuth callback:**
- Change to: `https://auth.yourdomain.com/callback`
3. **Update CMS config:**
```yaml
backend:
base_url: https://auth.yourdomain.com
```
---
## Cost
**Cloudflare Workers Free Tier**:
- 100,000 requests/day
- 10ms CPU time per request
- More than enough for CMS authentication
**Typical usage**: 50-100 requests/month for small teams
---
## Additional Resources
- **Official Auth Worker**: https://github.com/sveltia/sveltia-cms-auth
- **Sveltia CMS Docs**: https://github.com/sveltia/sveltia-cms
- **Wrangler Docs**: https://developers.cloudflare.com/workers/wrangler/
- **OAuth 2.0 Spec**: https://oauth.net/2/
---
**Last Updated**: 2025-10-24

26
templates/cloudflare-workers/wrangler.jsonc Normal file
View File

@@ -0,0 +1,26 @@
{
"name": "sveltia-cms-auth",
"main": "src/index.ts",
"compatibility_date": "2025-10-24",
"account_id": "", // Add your Cloudflare account ID here
// Environment variables (set via: npx wrangler secret put VARIABLE_NAME)
// Required:
// - GITHUB_CLIENT_ID: Your GitHub OAuth App Client ID
// - GITHUB_CLIENT_SECRET: Your GitHub OAuth App Client Secret
//
// Optional:
// - GITLAB_APPLICATION_ID: Your GitLab Application ID
// - GITLAB_SECRET: Your GitLab Application Secret
// - ALLOWED_DOMAINS: Comma-separated list of allowed domains (e.g., "yourdomain.com,*.yourdomain.com")
"vars": {
// Public variables (safe to commit)
"ENVIRONMENT": "production"
},
// For development
"dev": {
"port": 8787
}
}

52
templates/collections/blog-posts.yml Normal file
View File

@@ -0,0 +1,52 @@
# Blog Post Collection Template
# Copy this collection definition to your admin/config.yml
- name: posts
label: Blog Posts
folder: content/posts # Adjust for your framework (e.g., _posts for Jekyll)
create: true
slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
format: yaml # or md, toml, json
fields:
- label: Title
name: title
widget: string
hint: Post title
- label: Date
name: date
widget: datetime
date_format: 'YYYY-MM-DD'
time_format: 'HH:mm:ss'
format: 'YYYY-MM-DDTHH:mm:ssZ'
- label: Draft
name: draft
widget: boolean
default: true
hint: Set to false to publish
- label: Featured Image
name: image
widget: image
required: false
- label: Excerpt / Description
name: description
widget: text
required: false
hint: Short description for SEO
- label: Tags
name: tags
widget: list
required: false
- label: Categories
name: categories
widget: list
required: false
- label: Body
name: body
widget: markdown

45
templates/collections/docs-pages.yml Normal file
View File

@@ -0,0 +1,45 @@
# Documentation Page Collection Template
# Copy this collection definition to your admin/config.yml
- name: docs
label: Documentation
folder: content/docs # Adjust for your framework
create: true
slug: '{{slug}}'
format: yaml
fields:
- label: Title
name: title
widget: string
- label: Description
name: description
widget: text
required: false
hint: Page description for SEO
- label: Order / Weight
name: weight
widget: number
value_type: int
required: false
hint: Sort order (lower numbers appear first)
- label: Category
name: category
widget: select
options:
- Getting Started
- Guides
- API Reference
- Advanced
required: false
- label: Draft
name: draft
widget: boolean
default: false
- label: Body
name: body
widget: markdown

78
templates/collections/landing-pages.yml Normal file
View File

@@ -0,0 +1,78 @@
# Landing Page Collection Template (Structured Content)
# Copy this collection definition to your admin/config.yml
- name: pages
label: Landing Pages
folder: content/pages
create: true
slug: '{{slug}}'
format: json # JSON for structured data
fields:
- label: Title
name: title
widget: string
- label: SEO
name: seo
widget: object
fields:
- label: Meta Title
name: metaTitle
widget: string
required: false
- label: Meta Description
name: metaDescription
widget: text
required: false
- label: OG Image
name: ogImage
widget: image
required: false
- label: Hero Section
name: hero
widget: object
fields:
- label: Headline
name: headline
widget: string
- label: Subheadline
name: subheadline
widget: text
- label: Hero Image
name: image
widget: image
required: false
- label: CTA Button
name: cta
widget: object
fields:
- label: Text
name: text
widget: string
- label: URL
name: url
widget: string
- label: Features
name: features
widget: list
required: false
fields:
- label: Title
name: title
widget: string
- label: Description
name: description
widget: text
- label: Icon
name: icon
widget: image
required: false

113
templates/hugo/config.yml Normal file
View File

@@ -0,0 +1,113 @@
# Sveltia CMS Configuration for Hugo
# Place this file in: static/admin/config.yml
backend:
name: github
repo: owner/repo # Change to your GitHub repository (e.g., jezweb/my-blog)
branch: main # Change if your default branch is different
base_url: https://your-worker.workers.dev # Your Cloudflare Workers OAuth proxy URL
# Media storage
media_folder: static/images/uploads # Where uploaded files are saved
public_folder: /images/uploads # URL path for content files
# Optional: Image optimization
media_libraries:
default:
config:
max_file_size: 5242880 # 5 MB in bytes
slugify_filename: true
transformations:
raster_image:
format: webp # Convert to WebP
quality: 85
width: 2048
height: 2048
svg:
optimize: true
# Collections (content types)
collections:
# Blog Posts
- name: posts
label: Blog Posts
folder: content/posts
create: true
slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
format: yaml # Hugo supports yaml, toml, json
fields:
- label: Title
name: title
widget: string
hint: Post title (required)
- label: Date
name: date
widget: datetime
date_format: 'YYYY-MM-DD'
time_format: 'HH:mm:ss'
format: 'YYYY-MM-DDTHH:mm:ssZ'
hint: Publication date
- label: Draft
name: draft
widget: boolean
default: true
hint: Set to false to publish
- label: Featured Image
name: image
widget: image
required: false
hint: Main post image
- label: Excerpt
name: description
widget: text
required: false
hint: Short description for SEO and previews
- label: Tags
name: tags
widget: list
required: false
hint: Post tags (comma-separated)
- label: Categories
name: categories
widget: list
required: false
hint: Post categories
- label: Body
name: body
widget: markdown
hint: Post content
# Documentation Pages (optional)
- name: docs
label: Documentation
folder: content/docs
create: true
slug: '{{slug}}'
format: yaml
fields:
- label: Title
name: title
widget: string
- label: Description
name: description
widget: text
required: false
- label: Weight
name: weight
widget: number
value_type: int
hint: Sort order (lower numbers appear first)
required: false
- label: Body
name: body
widget: markdown

12
templates/hugo/index.html Normal file
View File

@@ -0,0 +1,12 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Content Manager</title>
</head>
<body>
<!-- Sveltia CMS -->
<script src="https://unpkg.com/@sveltia/cms@0.113.3/dist/sveltia-cms.js" type="module"></script>
</body>
</html>

82
templates/jekyll/config.yml Normal file
View File

@@ -0,0 +1,82 @@
# Sveltia CMS Configuration for Jekyll
# Place this file in: admin/config.yml
backend:
name: github
repo: owner/repo # Change to your GitHub repository
branch: main # or 'gh-pages' if using GitHub Pages source branch
base_url: https://your-worker.workers.dev # Your Cloudflare Workers OAuth proxy URL
# Media storage
media_folder: assets/images/uploads
public_folder: /assets/images/uploads
# Optional: Image optimization
media_libraries:
default:
config:
max_file_size: 5242880 # 5 MB
slugify_filename: true
transformations:
raster_image:
format: webp
quality: 85
width: 2048
height: 2048
# Collections
collections:
# Blog Posts
- name: posts
label: Blog Posts
folder: _posts
create: true
slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
fields:
- label: Layout
name: layout
widget: hidden
default: post
- label: Title
name: title
widget: string
- label: Date
name: date
widget: datetime
date_format: 'YYYY-MM-DD'
time_format: 'HH:mm:ss'
format: 'YYYY-MM-DD HH:mm:ss ZZ'
- label: Categories
name: categories
widget: list
required: false
- label: Tags
name: tags
widget: list
required: false
- label: Featured Image
name: image
widget: image
required: false
- label: Body
name: body
widget: markdown
# Pages
- name: pages
label: Pages
files:
- name: about
label: About Page
file: about.md
fields:
- { label: Layout, name: layout, widget: hidden, default: page }
- { label: Title, name: title, widget: string }
- { label: Permalink, name: permalink, widget: hidden, default: /about/ }
- { label: Body, name: body, widget: markdown }

12
templates/jekyll/index.html Normal file
View File

@@ -0,0 +1,12 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Content Manager</title>
</head>
<body>
<!-- Sveltia CMS -->
<script src="https://unpkg.com/@sveltia/cms@0.113.3/dist/sveltia-cms.js" type="module"></script>
</body>
</html>