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.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
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.
Complete skill for integrating Sveltia CMS into static site projects.
What is Sveltia CMS?
Sveltia CMS is a Git-based lightweight headless content management system built from scratch as the modern successor to Decap CMS (formerly Netlify CMS). It provides a fast, intuitive editing interface for content stored in Git repositories.
Key Features
Lightweight & Fast
Bundle size: <500 KB (minified/brotlied) vs 1.5-2.6 MB for competitors
Built with Svelte compiler (no virtual DOM overhead)
Uses GraphQL APIs for instant content fetching
Relevance-based search across all content
Modern User Experience
Intuitive admin interface with full viewport utilization
Dark mode support (follows system preferences)
Mobile and tablet optimized
Drag-and-drop file uploads with multiple file support
Real-time preview with instant updates
Git-Native Architecture
Content stored as Markdown, MDX, YAML, TOML, or JSON
Full version control and change history
No vendor lock-in - content lives with code
Supports GitHub, GitLab, Gitea, Forgejo backends
Framework-Agnostic
Served as vanilla JavaScript bundle
Works with Hugo, Jekyll, 11ty, Gatsby, Astro, Next.js, SvelteKit
No React, Vue, or framework runtime dependencies
Compatible with any static site generator
First-Class Internationalization
Multiple language support built-in
One-click DeepL translation integration
Locale switching while editing
Flexible i18n structures (files, folders, single file)
Built-In Image Optimization
Automatic WebP conversion
Client-side resizing and optimization
SVG optimization support
Configurable quality and dimensions
Current Versions
@sveltia/cms: 0.113.5 (October 2025)
Status: Public Beta (v1.0 expected early 2026)
Maturity: Production-ready (265+ issues solved from predecessor)
Create config file tailored to your content structure:
backend:
name: github
repo: owner/repo
branch: main
media_folder: <your-media-path>
public_folder: <your-public-path>
collections:
# Define based on your content structure
Access admin:
http://localhost:<port>/admin/
Authentication Setup
Choose the authentication method that fits your deployment platform.
# Set GitHub credentials
npx wrangler secret put GITHUB_CLIENT_ID
# Paste your Client ID
npx wrangler secret put GITHUB_CLIENT_SECRET
# Paste your Client Secret
# Optional: Restrict to specific domains
npx wrangler secret put ALLOWED_DOMAINS
# Example: yourdomain.com,*.yourdomain.com
Update CMS config:
# admin/config.yml
backend:
name: github
repo: owner/repo
branch: main
base_url: https://your-worker.workers.dev # ← Add this line
Test authentication:
Open your site's /admin/
Click "Login with GitHub"
Authorize the app
You should be redirected back to the CMS
Complete guide: See references/cloudflare-auth-setup.md
Template: See templates/cloudflare-workers/
Option 2: Vercel Serverless Functions
Best For: Vercel deployments
Steps:
Create API route:
// api/auth.ts
export default async function handler(req, res) {
// OAuth handling logic
// See templates/vercel-serverless/api-auth.ts
}
Template: See templates/collections/landing-pages.yml
Internationalization (i18n) Setup
Sveltia CMS has first-class i18n support with multiple structure options.
Multiple Files Structure (Recommended)
Best for: Hugo, Jekyll with separate locale files
i18n:
structure: multiple_files
locales: [en, fr, de, ja]
default_locale: en
collections:
- name: posts
label: Blog Posts
folder: content/posts
create: true
i18n: true # Enable i18n for this collection
fields:
- label: Title
name: title
widget: string
i18n: true # Translatable field
- label: Date
name: date
widget: datetime
i18n: duplicate # Same value across locales
- label: Body
name: body
widget: markdown
i18n: true
Result: Creates files like:
content/posts/hello-world.en.md
content/posts/hello-world.fr.md
content/posts/hello-world.de.md
Multiple Folders Structure
Best for: Next.js, Astro with locale directories
i18n:
structure: multiple_folders
locales: [en, fr, de]
default_locale: en
collections:
- name: blog
label: Blog Posts
folder: content/{{locale}}/blog # {{locale}} placeholder
create: true
i18n: true
fields:
# Same as above
Result: Creates files like:
content/en/blog/hello-world.md
content/fr/blog/hello-world.md
content/de/blog/hello-world.md
Single File Structure
Best for: i18n libraries that manage translations in one file
---
title: Post 1
---
--- # ← Remove this extra separator
title: Post 2
---
Problem: Incorrect indentation
# ❌ Bad - inconsistent indentation
fields:
- name: title
label: Title # Extra space
- name: date
label: Date
# ✅ Good - consistent 2-space indentation
fields:
- name: title
label: Title
- name: date
label: Date
Problem: Smart quotes
# ❌ Bad - smart quotes from copy-paste
title: "Hello World" # Curly quotes
# ✅ Good - straight quotes
title: "Hello World" # Straight quotes
Step 3: Auto-fix with yamlfmt:
# Install
go install github.com/google/yamlfmt/cmd/yamlfmt@latest
# Fix all files
find content -name "*.md" -exec yamlfmt {} \;
Prevention:
Use YAML-aware editors (VS Code with YAML extension)
Enable YAML schema validation
Run yamllint in pre-commit hooks
4. ❌ Content Not Listing in CMS
Error Message:
"No entries found"
Empty content list
"Failed to load entries"
Symptoms:
Admin loads but shows no content
Collections appear empty
Files exist in repository but CMS doesn't see them
Causes:
Format mismatch (config expects TOML, files are YAML)
Incorrect folder path
File extension doesn't match format
Git backend not connected
Solution:
Step 1: Verify folder path matches actual files:
# Config says:
collections:
- name: posts
folder: content/posts # Expects files here
# Check actual location:
ls -la content/posts # Files must exist here
Step 2: Match format to actual files:
# If files are: content/posts/hello.md with YAML frontmatter
collections:
- name: posts
folder: content/posts
format: yaml # or md (same as yaml for .md files)
# If files are: content/posts/hello.toml
collections:
- name: posts
folder: content/posts
format: toml
extension: toml
Step 3: Check file extensions:
# Config expects .md files
ls content/posts/*.md # Should show files
# If files have different extension:
# Either rename files OR set extension in config
Step 4: Verify Git backend connection:
backend:
name: github
repo: owner/repo # Must be correct owner/repo
branch: main # Must be correct branch
Prevention:
Keep folder paths relative to repository root
Match format to actual file format
Test with one file first before creating collection
5. ❌ "SVELTIA is not defined" Error
Error Message:
Console error: Uncaught ReferenceError: SVELTIA is not defined
# After build, check output directory
ls -la public/admin/ # or _site/admin/ or dist/admin/
Prevention:
Test admin page access before deploying
Add admin directory to version control
Document admin path in project README
7. ❌ Images Not Uploading (HEIC Format)
Error Message:
"Unsupported file format"
"Failed to upload image"
Image appears but doesn't save
Symptoms:
iPhone photos won't upload
HEIC files rejected
Only JPEG/PNG work
Causes:
HEIC format not supported by browsers
Image too large (exceeds max_file_size)
Media folder path incorrect
Solution:
Step 1: Convert HEIC to JPEG:
On Mac:
# Convert single file
sips -s format jpeg image.heic --out image.jpg
# Batch convert
for f in *.heic; do sips -s format jpeg "$f" --out "${f%.heic}.jpg"; done
# Your existing Decap config.yml works as-is!
backend:
name: github
repo: owner/repo
collections:
# ... no changes needed
Step 3: Test locally:
# Start your site's dev server
hugo server # or jekyll serve, or npm run dev
# Visit /admin/ and test:
# - Login
# - Content listing
# - Editing
# - Saving
# - Media uploads
Step 4: Deploy:
git add static/admin/index.html # or your admin path
git commit -m "Migrate to Sveltia CMS"
git push
That's it! Your content, collections, and workflows remain unchanged.
What's Different?
Config Compatibility: 100% compatible
UI Changes:
Faster interface (no virtual DOM)
Better mobile experience
Dark mode support
Improved search
Performance Improvements:
5x smaller bundle (300 KB vs 1.5 MB)
Instant content loading (GraphQL)
No API rate limit issues
New Features:
DeepL translation integration
Image optimization built-in
UUID slug generation
Better i18n support
Not Supported:
Git Gateway backend (for performance reasons)
Azure backend (may be added later)
Bitbucket backend (may be added later)
Workaround: Use Cloudflare Workers or Vercel OAuth proxy instead.
Testing Checklist
Before fully migrating, test these workflows:
Login with OAuth
View content list
Create new entry
Edit existing entry
Upload images
Publish/unpublish
Search content
Switch between collections
Mobile editing (if applicable)
i18n switching (if applicable)
Complete guide: See references/migration-from-decap.md
Deployment Patterns
Cloudflare Pages
Best For: Static sites with Cloudflare ecosystem
Steps:
Connect Git repository to Cloudflare Pages:
Dashboard > Pages > Create Project
Connect GitHub/GitLab
Select repository
Configure build settings:
Build command: hugo # or jekyll build, or npm run build
Build output directory: public # or _site, or dist
Root directory: /
Deploy OAuth Worker (see Cloudflare Workers OAuth section)
This skill prevents 8 common errors (100% prevention rate):
✅ OAuth authentication failures
✅ TOML front matter generation bugs
✅ YAML parse errors (strict validation)
✅ Content not listing in CMS
✅ "SVELTIA is not defined" errors
✅ 404 on /admin page
✅ Image upload failures (HEIC format)
✅ CORS / COOP policy errors
Quick Start Examples
Example 1: Hugo Blog with Cloudflare OAuth
# 1. Create Hugo site
hugo new site my-blog
cd my-blog
# 2. Create admin directory
mkdir -p static/admin
# 3. Copy templates
cp [path-to-skill]/templates/hugo/index.html static/admin/
cp [path-to-skill]/templates/hugo/config.yml static/admin/
# 4. Deploy OAuth Worker
git clone https://github.com/sveltia/sveltia-cms-auth
cd sveltia-cms-auth
npx wrangler deploy
# 5. Configure and test
hugo server
open http://localhost:1313/admin/
# 1. Update script tag in admin/index.html
sed -i 's|decap-cms|@sveltia/cms|g' static/admin/index.html
sed -i 's|decap-cms.js|sveltia-cms.js" type="module|g' static/admin/index.html
# 2. Test locally
hugo server
open http://localhost:1313/admin/
# 3. Deploy
git add static/admin/index.html
git commit -m "Migrate to Sveltia CMS"
git push
Production Examples
Hugo Documentation: 0deepresearch.com (Hugo + GitHub Pages + Sveltia)
