sveltia-cms（斯维尔蒂亚 CMS）

Sveltia CMS Skill

Complete skill for integrating Sveltia CMS into static site projects.

Current Versions

• @sveltia/cms: 0.128.5 (verified January 2026)
• Status: Public Beta (v1.0 expected early 2026)
• Maturity: Production-ready (270+ issues solved from predecessor)

When to Use This Skill

✅ Use Sveltia CMS When:

• Git-based workflow desired (content as Markdown/YAML/TOML/JSON in repository)
• Lightweight solution required (<500 KB vs 1.5-2.6 MB for competitors)
• Migrating from Decap/Netlify CMS (drop-in replacement, change 1 line)
• Non-technical editors need access without Git knowledge

❌ Don't Use Sveltia CMS When:

• Real-time collaboration needed (multiple users editing simultaneously) - Use Sanity, Contentful, or TinaCMS instead
• Visual page building required (drag-and-drop) - Use Webflow, Builder.io instead
• React-specific visual editing needed - Use TinaCMS instead

Breaking Changes & Updates (v0.105.0+)

v0.127.0 (December 29, 2025) - slug_length Deprecation

DEPRECATION: The slug_length collection option is deprecated and will be removed in v1.0.

Migration:

# ❌ Deprecated (pre-v0.127.0)
collections:
  - name: posts
    slug_length: 50

# ✅ New (v0.127.0+)
slug:
  maxlength: 50

Timeline: Will be removed in Sveltia CMS 1.0 (expected early 2026).

Source: Release v0.127.0

v0.120.0 (November 24, 2025) - Author Template Tags

New Feature: Hidden widget now supports author template tags:

• {{author-email}} - Signed-in user's email
• {{author-login}} - Signed-in user's login name
• {{author-name}} - Signed-in user's display name

Usage:

fields:
  - label: Author Email
    name: author_email
    widget: hidden
    default: '{{author-email}}'

Commit message templates also support {{author-email}} tag.

v0.119.0 (November 16, 2025) - TOML Config Support

New Feature: Configuration files can now be written in TOML format (previously YAML-only).

Migration:

# admin/config.toml (NEW)
[backend]
name = "github"
repo = "owner/repo"
branch = "main"

media_folder = "static/images/uploads"
public_folder = "/images/uploads"

Recommendation: YAML is still preferred for better tooling support.

v0.118.0 (November 15, 2025) - TypeScript Breaking Change

BREAKING: Renamed SiteConfig export to CmsConfig for compatibility with Netlify/Decap CMS.

Migration:

// ❌ Old (v0.117.x)
import type { SiteConfig } from '@sveltia/cms';

// ✅ New (v0.118.0+)
import type { CmsConfig } from '@sveltia/cms';

const config: CmsConfig = {
  backend: { name: 'github', repo: 'owner/repo' },
  collections: [/* ... */],
};

Impact: TypeScript users only. Breaking change for type imports.

v0.117.0 (November 14, 2025) - Enhanced Validation

New Features:

• Exported CmsConfig type for direct TypeScript import
• Enhanced config validation for collection names, field types, and relation references
• Better error messages for invalid configurations

v0.115.0 (November 5, 2025) - Field-Specific Media Folders

New Feature: Override media_folder at the field level (not just collection level).

Usage:

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    media_folder: static/images/posts  # Collection-level default
    fields:
      - label: Featured Image
        name: image
        widget: image
        media_folder: static/images/featured  # ← Field-level override
        public_folder: /images/featured

      - label: Author Avatar
        name: avatar
        widget: image
        media_folder: static/images/avatars  # ← Another override
        public_folder: /images/avatars

Use case: Different media folders for different image types in same collection.

v0.113.5 (October 27, 2025) - Logo Deprecation

DEPRECATION: logo_url option is now deprecated. Migrate to logo.src.

Migration:

# ❌ Deprecated
logo_url: https://yourdomain.com/logo.svg

# ✅ New (v0.113.5+)
logo:
  src: https://yourdomain.com/logo.svg

v0.105.0 (September 15, 2024) - Security Breaking Change

BREAKING: sanitize_preview default changed to true for Markdown widget (XSS prevention).

Impact:

• Before v0.105.0: sanitize_preview: false (compatibility with Netlify/Decap CMS, but vulnerable to XSS)
• After v0.105.0: sanitize_preview: true (secure by default)

Migration:

collections:
  - name: posts
    fields:
      - label: Body
        name: body
        widget: markdown
        sanitize_preview: false  # ← Add ONLY if you trust all CMS users

Recommendation: Keep default (true) unless disabling fixes broken preview AND you fully trust all CMS users.

Configuration Options

Global Slug Options (v0.128.0+)

Configure slug generation behavior globally:

slug:
  encoding: unicode-normalized
  clean_accents: false
  sanitize_replacement: '-'
  lowercase: true   # Default: convert to lowercase (v0.128.0+)
  maxlength: 50     # Default: unlimited (v0.127.0+)

lowercase (v0.128.0+): Set to false to preserve original casing in slugs (e.g., "MyBlogPost" instead of "myblogpost").

Use case: Mixed-case URLs or file names where case matters.

Source: Release v0.128.0, GitHub Issue #594

Raw Format for Text Files (v0.126.0+)

New raw format allows editing files without front matter (CSV, JSON, YAML, plain text). Must have single body field with widget type: code, markdown, richtext, or text.

Use Cases:

• Edit configuration files (JSON, YAML)
• Manage CSV data
• Edit plain text files

Configuration:

collections:
  - name: config
    label: Configuration Files
    files:
      - label: Site Config
        name: site_config
        file: config.json
        format: raw  # ← NEW format type
        fields:
          - label: Config
            name: body
            widget: code
            default_language: json

Restrictions:

• Only one field allowed (must be named body)
• Widget must be: code, markdown, richtext, or text
• No front matter parsing

Source: Release v0.126.0

Number Field String Encoding (v0.125.0+)

New value_type option for Number field accepts int/string and float/string to save numbers as strings instead of numbers in front matter.

Use Case: Some static site generators or schemas require numeric values stored as strings (e.g., age: "25" instead of age: 25).

Configuration:

fields:
  - label: Age
    name: age
    widget: number
    value_type: int/string  # Saves as "25" not 25

  - label: Price
    name: price
    widget: number
    value_type: float/string  # Saves as "19.99" not 19.99

Source: Release v0.125.0, GitHub Issue #574

Editor Pane Locale via URL Query (v0.126.0+)

Override editor locale via URL query parameter ?_locale=fr to get edit links for specific locales.

Use Case: Generate direct edit links for translators or content editors for specific languages.

Example:

https://yourdomain.com/admin/#/collections/posts/entries/my-post?_locale=fr

Source: Release v0.126.0, GitHub Issue #585

Richtext Field Type Alias (v0.124.0+)

Added richtext as an alias for markdown widget to align with Decap CMS terminology. Both work identically.

Configuration:

fields:
  - label: Body
    name: body
    widget: richtext  # ← NEW alias for markdown

Future: HTML output support planned for richtext field type.

Source: Release v0.124.0

Setup Pattern (Framework-Agnostic)

All frameworks follow the same pattern:

1. Create admin directory in public/static folder:

- Hugo: static/admin/ - Jekyll: admin/ - 11ty: admin/ (with passthrough copy) - Astro: public/admin/ - Next.js: public/admin/

1. Create admin/index.html: <!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> <script src="https://unpkg.com/@sveltia/cms@0.128.5/dist/sveltia-cms.js" type="module"></script> </body> </html>
2. Create admin/config.yml: backend: name: github repo: owner/repo branch: main base_url: https://your-worker.workers.dev # OAuth proxy (required) media_folder: static/images/uploads # Framework-specific path public_folder: /images/uploads collections: - name: posts label: Blog Posts folder: content/posts create: true fields: - {label: 'Title', name: 'title', widget: 'string'} - {label: 'Date', name: 'date', widget: 'datetime'} - {label: 'Body', name: 'body', widget: 'markdown'}
3. Access admin: http://localhost:<port>/admin/

Framework-specific details: See templates/ directory for complete examples.

Authentication: Cloudflare Workers OAuth (Recommended)

Why Cloudflare Workers: Fastest, free tier available, works with any deployment platform.

Steps:

1. Deploy Worker: git clone https://github.com/sveltia/sveltia-cms-auth cd sveltia-cms-auth npm install npx wrangler deploy
2. Register OAuth App on GitHub:

- Go to https://github.com/settings/developers - Click "New OAuth App" - Authorization callback URL: https://your-worker.workers.dev/callback - Save Client ID and Client Secret

1. Configure Worker Environment Variables: npx wrangler secret put GITHUB_CLIENT_ID # Paste your Client ID npx wrangler secret put GITHUB_CLIENT_SECRET # Paste your Client Secret
2. Update CMS config: backend: name: github repo: owner/repo branch: main base_url: https://your-worker.workers.dev # ← Add this line
3. Test authentication:

- Open /admin/ - Click "Login with GitHub" - Should redirect to GitHub → Authorize → Back to CMS

Alternative: Vercel serverless functions - See templates/vercel-serverless/

Common Errors & Solutions

This skill prevents 10 common errors encountered when setting up Sveltia CMS.

1. ❌ OAuth Authentication Failures

Error Message:

• "Error: Failed to authenticate"
• Redirect to https://api.netlify.com/auth instead of GitHub login

Symptoms:

• Login button does nothing
• Authentication popup closes immediately

Causes:

• Missing base_url in backend config
• Incorrect OAuth proxy URL
• Wrong GitHub OAuth callback URL

Solution:

Step 1: Verify config.yml has base_url:

backend:
  name: github
  repo: owner/repo
  branch: main
  base_url: https://your-worker.workers.dev  # ← Must be present

Step 2: Check GitHub OAuth App callback:

• Should be: https://your-worker.workers.dev/callback
• NOT: https://yourdomain.com/callback

Step 3: Test Worker directly:

curl https://your-worker.workers.dev/health
# Should return: {"status": "ok"}

2. ❌ TOML Front Matter Errors

Error Message:

• "Parse error: Invalid TOML"
• Files missing +++ delimiters

Symptoms:

• New files created by CMS don't parse in Hugo
• Content appears above body separator

Causes:

• Sveltia's TOML generation is buggy in beta
• Mixed TOML/YAML in same collection

Solution:

Use YAML instead of TOML (recommended):

collections:
  - name: posts
    folder: content/posts
    format: yaml  # or md (Markdown with YAML frontmatter)
    # NOT: format: toml

If you must use TOML:

1. Manually fix delimiters after CMS saves
2. Use pre-commit hook to validate TOML
3. Wait for beta fixes (track GitHub issues)

3. ❌ YAML Parse Errors

Error Message:

• "YAML parse error: Invalid YAML"
• "Error: Duplicate key 'field_name'"

Symptoms:

• Existing posts won't load in CMS
• CMS shows empty fields

Causes:

• Sveltia is stricter than Hugo/Jekyll about YAML formatting
• Incorrect indentation or smart quotes

Solution:

Step 1: Validate YAML:

pip install yamllint
find content -name "*.md" -exec yamllint {} \;

Step 2: Common fixes:

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:

go install github.com/google/yamlfmt/cmd/yamlfmt@latest
find content -name "*.md" -exec yamlfmt {} \;

4. ❌ Content Not Listing in CMS

Error Message:

• "No entries found"
• "Failed to load entries"

Symptoms:

• Admin loads but shows no content
• Files exist in repository but CMS doesn't see them

Causes:

• Format mismatch (config expects TOML, files are YAML)
• Incorrect folder path

Solution:

Step 1: Verify folder path:

# 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)

5. ❌ "SVELTIA is not defined" Error

Error Message:

• Console error: Uncaught ReferenceError: SVELTIA is not defined

Symptoms:

• Admin page shows white screen

Causes:

• Missing type="module" attribute

Solution:

Use correct script tag:

<!-- ✅ 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>

Use version pinning (recommended):

<script src="https://unpkg.com/@sveltia/cms@0.128.5/dist/sveltia-cms.js" type="module"></script>

6. ❌ 404 on /admin

Error Message:

• "404 Not Found" when visiting /admin/

Symptoms:

• Works locally but not in production

Causes:

• Admin directory not in correct location for framework

Solution:

Framework-specific fixes:

Hugo: Files in static/ are automatically copied

Jekyll: Add to _config.yml:

include:
  - admin

11ty: Add to .eleventy.js:

module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy('admin');
};

Astro: Files in public/ are automatically copied

7. ❌ Images Not Uploading (HEIC Format)

Error Message:

• "Unsupported file format"

Symptoms:

• iPhone photos won't upload

Causes:

• HEIC format not supported by browsers

Solution:

On iPhone:

• Settings > Camera > Formats > Most Compatible
• This saves photos as JPEG instead of HEIC

Or enable image optimization:

media_libraries:
  default:
    config:
      max_file_size: 10485760  # 10 MB
      transformations:
        raster_image:
          format: webp  # Auto-converts to WebP
          quality: 85

8. ❌ Datetime Widget Format Strictness

Error Message:

• Silent data loss (no error shown)
• Date fields show blank in CMS

Symptoms:

• Posts with existing dates appear blank when editing
• Saving overwrites dates with blank values
• Hugo marks posts as "future" and skips building them

Causes:

• Default datetime widget outputs timestamps WITHOUT timezone suffix
• When format is specified, Sveltia becomes strict - existing entries with different formats show as blank
• Hugo infers UTC when timezone missing, causing timezone issues

⚠️ CRITICAL: Format Strictness Warning (v0.124.1+)

When you specify a format option, Sveltia becomes strict:

• Existing entries with different formats show as blank
• Saving will overwrite with blank value (SILENT DATA LOSS)
• No error message shown

Solution:

Option 1: Use picker_utc (Recommended)

fields:
  - label: Date
    name: date
    widget: datetime
    picker_utc: true  # Most flexible - outputs with timezone

Option 2: Specify format with timezone (RISKY - see warning above)

fields:
  - label: Date
    name: date
    widget: datetime
    format: "YYYY-MM-DDTHH:mm:ss.SSSZ"  # Only if ALL existing dates match this format

Option 3: Configure Hugo to accept missing timezone

# config.toml
[frontmatter]
  date = [":default", ":fileModTime"]

Prevention:

1. Don't specify format if you have mixed date formats
2. Normalize all dates first before adding format
3. Use picker_utc: true instead (more flexible)

Source: GitHub Issue #565, fixed in v0.126.0 (improved date parser but format strictness remains)

9. ❌ GDPR Violation: Google Fonts CDN

Error Message:

• No error shown (privacy compliance issue)

Symptoms:

• Privacy-focused sites blocked from using Sveltia
• EU public sector cannot adopt
• GDPR non-compliance

Causes:

• Sveltia loads Google Fonts and Material Symbols from Google CDN without user consent
• Google tracks font usage and collects IP addresses
• Violates EU data protection law

⚠️ Impact: Blocking issue for EU public sector and privacy-focused sites

Solution (Vite Plugin - Recommended):

// vite.config.ts
import { defineConfig, type Plugin } from 'vite'

function ensureGDPRCompliantFonts(): Plugin {
  const fontsURLRegex = /fonts\.googleapis\.com\/css2/g
  const replacement = 'fonts.bunny.net/css'
  return {
    name: 'gdpr-compliant-fonts',
    enforce: 'post',
    transform(code) {
      if (fontsURLRegex.test(code)) {
        return code.replaceAll(fontsURLRegex, replacement)
      }
    },
  }
}

export default defineConfig({
  plugins: [ensureGDPRCompliantFonts()],
})

Alternative Solutions:

Option 2: Bunny Fonts (1:1 Google Fonts replacement)

• Use https://fonts.bunny.net instead of fonts.googleapis.com
• EU-based, GDPR-compliant
• Same API as Google Fonts

Option 3: Self-hosted fonts

• Use @fontsource npm packages
• Bundle fonts with application
• No external requests

Maintainer Response:

• Acknowledged issue
• Plans to add system font option (post-v1.0)
• Sveltia itself collects no data (fonts are only concern)

Source: GitHub Issue #443

10. ❌ CORS / COOP Policy Errors

Error Message:

• "Authentication Aborted"
• "Cross-Origin-Opener-Policy blocked"

Symptoms:

• OAuth popup opens then closes

Causes:

• Strict Cross-Origin-Opener-Policy header blocking OAuth

Solution:

Cloudflare Pages (_headers file):

/*
  Cross-Origin-Opener-Policy: same-origin-allow-popups
  # NOT: same-origin (this breaks OAuth)

Netlify (_headers file):

/*
  Cross-Origin-Opener-Policy: same-origin-allow-popups

Vercel (vercel.json):

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cross-Origin-Opener-Policy",
          "value": "same-origin-allow-popups"
        }
      ]
    }
  ]
}

Fixed Issues (Historical Reference)

These issues were present in earlier versions but have been fixed. Documented here for reference.

✅ Paths with Parentheses Break Entry Loading (Fixed in v0.128.1)

Issue: Sveltia CMS failed to load existing entries when the path option contains parentheses (). This affected Next.js/Nextra users using route groups like app/(content)/(writing)/.

Symptoms (pre-v0.128.1):

• Creating new entries worked
• Loading/listing existing entries failed silently
• CMS showed "No entries found" despite files existing

Example that failed:

collections:
  - name: pages
    folder: app/(pages)
    path: "{{slug}}/page"  # ← Failed to load existing entries
    extension: mdx

Status: Fixed in v0.128.1 (January 13, 2026)

Source: GitHub Issue #596

✅ Root Folder Collections Break GitHub Backend (Fixed in v0.125.0)

Issue: Collections with folder: "" or folder: "." or folder: "/" failed when creating new entries via GitHub backend. GraphQL query incorrectly constructed path starting with / (absolute) instead of relative path.

Symptoms (pre-v0.125.0):

• Worked locally via browser File API
• Failed with GitHub backend (GraphQL error)
• Leading slash broke GraphQL mutation

Example that failed:

collections:
  - name: root-pages
    folder: ""  # or "." or "/"
    # ← Broke when creating entries via GitHub backend

Use Case: VitePress and other frameworks storing content at repository root.

Status: Fixed in v0.125.0 (December 20, 2025)

Source: GitHub Issue #580

Migration from Decap CMS

Sveltia CMS is a drop-in replacement for Decap CMS.

Step 1: Update script tag (1 line change):

<!-- OLD: Decap CMS -->
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>

<!-- NEW: Sveltia CMS -->
<script src="https://unpkg.com/@sveltia/cms@0.128.5/dist/sveltia-cms.js" type="module"></script>

Step 2: Keep existing config.yml (no changes needed)

Step 3: Test locally (verify login, content listing, editing, saving)

That's it! Your content, collections, and workflows remain unchanged.

Not Supported:

• Git Gateway backend (for performance reasons)
• Azure backend (may be added later)

Workaround: Use Cloudflare Workers or Vercel OAuth proxy instead.

Bundled Resources

Templates

• hugo/ - Complete Hugo blog setup
• jekyll/ - Jekyll site configuration
• 11ty/ - Eleventy blog setup
• astro/ - Astro content collections
• cloudflare-workers/ - OAuth proxy implementation
• vercel-serverless/ - Vercel auth functions
• collections/ - Pre-built collection patterns

References

• common-errors.md - Extended error troubleshooting
• migration-from-decap.md - Complete migration guide
• cloudflare-auth-setup.md - Step-by-step OAuth setup
• config-reference.md - Full config.yml documentation

Scripts

• init-sveltia.sh - Automated setup for new projects
• deploy-cf-auth.sh - Deploy Cloudflare Workers OAuth

Official Documentation

• Documentation Site: https://sveltiacms.app/en/docs (under active development - some sections may be incomplete)
• GitHub: https://github.com/sveltia/sveltia-cms
• OAuth Worker: https://github.com/sveltia/sveltia-cms-auth
• npm Package: https://www.npmjs.com/package/@sveltia/cms
• Discussions: https://github.com/sveltia/sveltia-cms/discussions

Note: The official documentation site is being actively developed. GitHub README remains a useful fallback for some topics.

Token Efficiency

Estimated Savings: 65-70% (~6,300 tokens saved)

Without Skill (~9,500 tokens):

• Framework setup trial & error: 2,500 tokens
• OAuth configuration attempts: 2,500 tokens
• Error troubleshooting: 2,500 tokens
• Deployment configuration: 2,000 tokens

With Skill (~3,200 tokens):

• Skill loading (SKILL.md): 2,000 tokens
• Template selection: 400 tokens
• Project-specific adjustments: 800 tokens

Errors Prevented

This skill prevents 10 common errors (100% prevention rate):

1. ✅ OAuth authentication failures
2. ✅ TOML front matter generation bugs
3. ✅ YAML parse errors (strict validation)
4. ✅ Content not listing in CMS
5. ✅ "SVELTIA is not defined" errors
6. ✅ 404 on /admin page
7. ✅ Image upload failures (HEIC format)
8. ✅ Datetime widget format strictness / timezone issues
9. ✅ GDPR violation (Google Fonts CDN)
10. ✅ CORS / COOP policy errors

Last Updated: 2026-01-21 Skill Version: 2.1.0 Sveltia CMS Version: 0.128.5 (Beta) Status: Production-ready, v1.0 GA expected early 2026 Changes: Added 6 new configuration options (slug lowercase, raw format, number string encoding, locale URL param, richtext alias, Gemini 2.5 Flash-Lite support), updated datetime error with format strictness warning, added GDPR Google Fonts workaround, documented 2 fixed historical issues, deprecated slug_length option