sveltia-cms

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sveltia CMS Skill

Sveltia CMS 使用技能

Complete skill for integrating Sveltia CMS into static site projects.

将Sveltia CMS集成到静态站点项目的完整指南。

What is Sveltia CMS?

什么是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.

Sveltia CMS 是一款基于Git的轻量级无头内容管理系统，作为Decap CMS（前身为Netlify CMS）的现代继任者从零构建。它为存储在Git仓库中的内容提供了快速、直观的编辑界面。

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

轻量且快速
- 包体积：<500 KB（压缩后），竞品为1.5-2.6 MB
- 基于Svelte编译器构建（无虚拟DOM开销）
- 使用GraphQL API实现即时内容获取
- 全内容相关性搜索
现代化用户体验
- 直观的管理界面，充分利用视口空间
- 支持深色模式（跟随系统偏好设置）
- 针对移动端和平板设备优化
- 支持多文件拖拽上传
- 实时预览，即时更新内容
原生Git架构
- 内容以Markdown、MDX、YAML、TOML或JSON格式存储
- 完整的版本控制和变更历史
- 无供应商锁定 - 内容与代码共存
- 支持GitHub、GitLab、Gitea、Forgejo作为后端
框架无关
- 以原生JavaScript包形式提供
- 可与Hugo、Jekyll、11ty、Gatsby、Astro、Next.js、SvelteKit配合使用
- 无需React、Vue或其他框架运行时依赖
- 兼容任何静态站点生成器
一流的国际化支持
- 内置多语言支持
- 一键集成DeepL翻译
- 编辑时可切换语言区域
- 灵活的国际化结构（文件、文件夹、单文件模式）
内置图片优化
- 自动转换为WebP格式
- 客户端侧调整大小与优化
- 支持SVG优化
- 可配置图片质量和尺寸

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)

@sveltia/cms: 0.113.5（2025年10月）
状态: 公开测试版（预计2026年初发布v1.0）
成熟度: 可用于生产环境（已解决前任产品的265+个问题）

When to Use This Skill

何时使用该技能

✅ Use Sveltia CMS When:

✅ 推荐使用Sveltia CMS的场景：

Building Static Sites
- Hugo blogs and documentation
- Jekyll sites and GitHub Pages
- 11ty (Eleventy) projects
- Gatsby marketing sites
- Astro content-heavy sites
Non-Technical Editors Need Access
- Marketing teams managing pages
- Authors writing blog posts
- Content teams without Git knowledge
- Clients needing easy content updates
Git-Based Workflow Desired
- Content versioning through Git
- Content review through pull requests
- Content lives with code in repository
- CI/CD integration for deployments
Lightweight Solution Required
- Performance-sensitive projects
- Mobile-first editing needed
- Quick load times critical
- Minimal bundle size important
Migrating from Decap/Netlify CMS
- Existing config.yml can be reused
- Drop-in replacement (change 1 line)
- Better performance and UX
- Active maintenance and bug fixes

构建静态站点时
- Hugo博客与文档站点
- Jekyll站点与GitHub Pages
- 11ty（Eleventy）项目
- Gatsby营销站点
- Astro内容密集型站点
非技术编辑需要内容访问权限时
- 营销团队管理页面内容
- 作者撰写博客文章
- 不懂Git的内容团队
- 需要便捷更新内容的客户
需要基于Git的工作流时
- 通过Git进行内容版本控制
- 通过拉取请求进行内容审核
- 内容与代码存储在同一仓库
- 集成CI/CD进行部署
需要轻量级解决方案时
- 对性能敏感的项目
- 需要移动端优先的编辑体验
- 页面加载速度至关重要
- 对包体积有严格要求
从Decap/Netlify CMS迁移时
- 现有config.yml可直接复用
- 即插即用替换（仅需修改1行代码）
- 更优的性能和用户体验
- 活跃的维护和Bug修复

❌ Don't Use Sveltia CMS When:

❌ 不推荐使用Sveltia CMS的场景：

Real-Time Collaboration Needed
- Multiple users editing simultaneously (Google Docs-style)
- Use Sanity, Contentful, or TinaCMS instead
Visual Page Building Required
- Drag-and-drop page builders needed
- Use Webflow, Builder.io, or TinaCMS (React) instead
Highly Dynamic Data
- E-commerce with real-time inventory
- Real-time dashboards or analytics
- Use traditional databases (D1, PostgreSQL) instead
React-Specific Visual Editing Needed
- In-context component editing
- Use TinaCMS instead (React-focused)

需要实时协作时
- 多用户同时编辑（类似Google Docs）
- 建议使用Sanity、Contentful或TinaCMS
需要可视化页面构建时
- 需要拖拽式页面构建器
- 建议使用Webflow、Builder.io或TinaCMS（React版）
处理高度动态数据时
- 带实时库存的电商站点
- 实时仪表盘或分析系统
- 建议使用传统数据库（D1、PostgreSQL）
需要React专属可视化编辑时
- 上下文内组件编辑
- 建议使用TinaCMS（专注于React）

Sveltia CMS vs TinaCMS

Use Sveltia for:

Hugo, Jekyll, 11ty, Gatsby (non-React SSGs)
Traditional CMS admin panel UX
Lightweight bundle requirements
Framework-agnostic projects

Use TinaCMS for:

React, Next.js, Astro (React components)
Visual in-context editing
Schema-driven type-safe content
Modern developer experience with TypeScript

Both are valid - Sveltia complements TinaCMS for different use cases.

选择Sveltia CMS的场景：

Hugo、Jekyll、11ty、Gatsby（非React静态站点生成器）
传统CMS管理面板用户体验
对包体积有轻量要求
框架无关的项目

选择TinaCMS的场景：

React、Next.js、Astro（React组件）
可视化上下文内编辑
基于Schema的类型安全内容
结合TypeScript的现代化开发者体验

两者均可 - Sveltia CMS与TinaCMS适用于不同场景，可互为补充。

Quick Start

快速开始

Load
references/framework-setup.md
for complete framework-specific setup (Hugo, Jekyll, 11ty, Astro, Next.js, Gatsby, SvelteKit).

如需完整的框架专属设置指南，请查看
references/framework-setup.md
（涵盖Hugo、Jekyll、11ty、Astro、Next.js、Gatsby、SvelteKit）。

Basic Setup Steps (Framework-Agnostic)

基础设置步骤（框架无关）

Create admin directory in your public folder (e.g.,
```
static/admin
```
,
```
public/admin
```
)
Create
admin/index.html
with Sveltia CMS script tag
Create
admin/config.yml
with backend and collections
Set up authentication → See
```
references/authentication-guide.md
```
Test locally by visiting
```
/admin/
```

Templates available in

templates/

directory for each framework.

在公共目录中创建admin文件夹（例如：
```
static/admin
```
、
```
public/admin
```
）
**创建
```
admin/index.html
```
**并添加Sveltia CMS脚本标签
**创建
```
admin/config.yml
```
**配置后端和集合
设置认证 → 查看
```
references/authentication-guide.md
```
本地测试，访问
```
/admin/
```
路径

模板资源：每个框架对应的模板存放在

templates/

目录中。

Authentication Setup

认证设置

Load
references/authentication-guide.md
for complete OAuth setup instructions.

如需完整的OAuth设置说明，请查看
references/authentication-guide.md
。

Quick Overview

快速概览

Method	Best For	Complexity
Cloudflare Workers	All deployments	Easy ⭐
Vercel Serverless	Vercel projects	Medium
Local Development	Dev only	Easy

Recommended: Cloudflare Workers OAuth (official, fast, free)

Templates: See

templates/cloudflare-workers/

and

templates/vercel-serverless/

方法	最佳适用场景	复杂度
Cloudflare Workers	所有部署场景	简单 ⭐
Vercel Serverless	Vercel项目	中等
本地开发	仅开发环境	简单

推荐方案：Cloudflare Workers OAuth（官方支持、快速、免费）

模板资源：查看

templates/cloudflare-workers/

和

templates/vercel-serverless/

Configuration

配置说明

Load
references/configuration-guide.md
for complete config.yml documentation, collection patterns, and i18n setup.

如需完整的config.yml文档、集合模式及国际化设置指南，请查看
references/configuration-guide.md
。

Essential Config Structure

核心配置结构

yaml

backend:
  name: github
  repo: owner/repo
  branch: main
  base_url: https://your-worker.workers.dev

media_folder: static/images
public_folder: /images

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    create: true
    fields:
      - { label: Title, name: title, widget: string }
      - { label: Body, name: body, widget: markdown }

Collection templates available in

templates/collections/

for blogs, docs, and landing pages.

i18n support: Multiple files, folders, or single file structures - see reference guide.

yaml

backend:
  name: github
  repo: owner/repo
  branch: main
  base_url: https://your-worker.workers.dev

media_folder: static/images
public_folder: /images

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    create: true
    fields:
      - { label: Title, name: title, widget: string }
      - { label: Body, name: body, widget: markdown }

集合模板：博客、文档和落地页对应的集合模板存放在

templates/collections/

目录中。

国际化支持：支持多文件、文件夹或单文件结构 - 请查看参考指南。

Common Errors & Solutions

常见错误与解决方案

This skill prevents 8 common errors. Top 3 shown below - load
references/error-catalog.md
for all 8 with complete solutions.

本技能可预防8类常见错误。以下为排名前三的错误 - 如需全部8类错误的详细解决方案，请查看
references/error-catalog.md
。

1. ❌ OAuth Authentication Failures

1. ❌ OAuth认证失败

Error: "Error: Failed to authenticate" / redirects to wrong domain

Quick Fix:

Verify
```
base_url
```
in
```
config.yml
```
points to your OAuth proxy
Check GitHub OAuth callback URL matches Worker URL

Test Worker:

curl https://your-worker.workers.dev/health

→ Load
references/error-catalog.md
Error #1 for complete solution

错误信息："Error: Failed to authenticate" / 重定向到错误域名

快速修复：

验证
```
config.yml
```
中的
```
base_url
```
指向正确的OAuth代理
检查GitHub OAuth回调URL与Worker URL是否匹配

测试Worker：

curl https://your-worker.workers.dev/health

→ 查看
references/error-catalog.md
中的错误#1获取完整解决方案

2. ❌ Content Not Listing in CMS

2. ❌ CMS中内容未显示

Error: "No entries found" / empty content list

Quick Fix:

Verify
```
folder
```
path matches actual file location
Match
```
format
```
to actual file format (yaml vs toml)
Check file extensions match config

→ Load
references/error-catalog.md
Error #4 for complete solution

错误信息："No entries found" / 内容列表为空

快速修复：

验证
```
folder
```
路径与实际文件位置一致
确保
```
format
```
与实际文件格式匹配（yaml或toml）
检查文件扩展名与配置是否一致

→ 查看
references/error-catalog.md
中的错误#4获取完整解决方案

3. ❌ CORS / COOP Policy Errors

3. ❌ CORS / COOP策略错误

Error: "Authentication Aborted" / OAuth popup closes

Quick Fix:

Set

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

in headers

Add OAuth proxy to CSP
```
connect-src
```

→ Load
references/error-catalog.md
Error #8 for complete solution

All 8 errors with detailed solutions: See

references/error-catalog.md

错误信息："Authentication Aborted" / OAuth弹窗关闭

快速修复：

在响应头中设置

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

将OAuth代理添加到CSP的
```
connect-src
```
中

→ 查看
references/error-catalog.md
中的错误#8获取完整解决方案

全部8类错误及详细解决方案：请查看

references/error-catalog.md

Migration from Decap CMS

从Decap CMS迁移

Sveltia is a drop-in replacement - just change the script tag!

html

<!-- 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/dist/sveltia-cms.js" type="module"></script>

Your existing

config.yml

works as-is. Load
references/migration-from-decap.md
for complete migration guide and testing checklist.

Sveltia CMS是即插即用的替代方案 - 仅需修改脚本标签即可！

html

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

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

您现有的

config.yml

可直接使用。如需完整的迁移指南和测试清单，请查看
references/migration-from-decap.md
。

Deployment

部署说明

Load
references/deployment-guide.md
for platform-specific deployment instructions (Cloudflare Pages, Vercel, Netlify, GitHub Pages).

如需平台专属部署指南，请查看
references/deployment-guide.md
（涵盖Cloudflare Pages、Vercel、Netlify、GitHub Pages）。

Quick Deployment Checklist

快速部署清单

Admin directory in correct public folder
OAuth proxy deployed and configured
```
base_url
```
set in config.yml
Build command configured
Test
```
/admin/
```
route after deployment

Admin目录放置在正确的公共文件夹中
OAuth代理已部署并配置完成
config.yml中已设置
```
base_url
```
构建命令已配置
部署后测试
```
/admin/
```
路径

When to Load References

何时查看参考文档

Load
references/framework-setup.md
when:

User needs framework-specific setup (Hugo, Jekyll, 11ty, Astro, etc.)
Setting up new Sveltia CMS installation
Troubleshooting framework-specific admin directory issues

Load
references/authentication-guide.md
when:

Setting up GitHub OAuth authentication
Deploying Cloudflare Workers OAuth proxy
Troubleshooting authentication errors
User asks about
```
base_url
```
configuration

Load
references/configuration-guide.md
when:

User needs complete
```
config.yml
```
examples
Setting up collections, fields, or widgets
Configuring media uploads, i18n, or workflows
User asks about specific configuration options

Load
references/error-catalog.md
when:

User encounters any errors during setup
Troubleshooting authentication, parsing, or deployment issues
User reports errors beyond the top 3 shown above

Load
references/deployment-guide.md
when:

Deploying to Cloudflare Pages, Netlify, or Vercel
Setting up OAuth proxy deployment
Troubleshooting production deployment issues

Load
references/migration-from-decap.md
when:

Migrating from Decap CMS / Netlify CMS
User asks about compatibility or migration steps

当以下情况时，查看
references/framework-setup.md
：

用户需要框架专属设置（Hugo、Jekyll、11ty、Astro等）
首次安装配置Sveltia CMS
排查框架专属的Admin目录问题

当以下情况时，查看
references/authentication-guide.md
：

设置GitHub OAuth认证
部署Cloudflare Workers OAuth代理
排查认证相关错误
用户询问
```
base_url
```
配置

当以下情况时，查看
references/configuration-guide.md
：

用户需要完整的
```
config.yml
```
示例
设置集合、字段或小部件
配置媒体上传、国际化或工作流
用户询问特定配置选项

当以下情况时，查看
references/error-catalog.md
：

用户在设置过程中遇到任何错误
排查认证、解析或部署问题
用户报告的错误超出上述前三类

当以下情况时，查看
references/deployment-guide.md
：

部署到Cloudflare Pages、Netlify或Vercel
部署OAuth代理
排查生产环境部署问题

当以下情况时，查看
references/migration-from-decap.md
：

从Decap CMS / Netlify CMS迁移
用户询问兼容性或迁移步骤

Resources

资源

Templates:

templates/hugo/

templates/jekyll/

templates/cloudflare-workers/

Official Docs: https://github.com/sveltia/sveltia-cms OAuth Worker: https://github.com/sveltia/sveltia-cms-auth

模板：

templates/hugo/

、

templates/jekyll/

、

templates/cloudflare-workers/

官方文档：https://github.com/sveltia/sveltia-cms OAuth Worker：https://github.com/sveltia/sveltia-cms-auth

Package Information

包信息

Current Version: @sveltia/cms@0.113.5 (October 2025) Status: Production-ready, v1.0 expected early 2026

Last Updated: 2025-10-24

当前版本：@sveltia/cms@0.113.5（2025年10月）状态：可用于生产环境，预计2026年初发布v1.0

最后更新：2025-10-24