sveltia-cms by jezweb/claude-skills
npx skills add https://github.com/jezweb/claude-skills --skill sveltia-cms用于将 Sveltia CMS 集成到静态站点项目的完整技能。
弃用 : slug_length 集合选项已弃用,将在 v1.0 中移除。
迁移 :
# ❌ 已弃用 (v0.127.0 之前)
collections:
- name: posts
slug_length: 50
# ✅ 新方式 (v0.127.0+)
slug:
maxlength: 50
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
时间线 : 将在 Sveltia CMS 1.0 中移除 (预计 2026 年初)。
来源 : 发布 v0.127.0
新功能 : 隐藏小部件现在支持作者模板标签:
{{author-email}} - 已登录用户的电子邮件{{author-login}} - 已登录用户的登录名{{author-name}} - 已登录用户的显示名称用法 :
fields:
- label: Author Email
name: author_email
widget: hidden
default: '{{author-email}}'
提交消息模板 也支持 {{author-email}} 标签。
新功能 : 配置文件现在可以用 TOML 格式编写 (之前仅支持 YAML)。
迁移 :
# admin/config.toml (新)
[backend]
name = "github"
repo = "owner/repo"
branch = "main"
media_folder = "static/images/uploads"
public_folder = "/images/uploads"
建议 : 为了获得更好的工具支持,仍推荐使用 YAML。
破坏性变更 : 为了与 Netlify/Decap CMS 兼容,将 SiteConfig 导出重命名为 CmsConfig。
迁移 :
// ❌ 旧方式 (v0.117.x)
import type { SiteConfig } from '@sveltia/cms';
// ✅ 新方式 (v0.118.0+)
import type { CmsConfig } from '@sveltia/cms';
const config: CmsConfig = {
backend: { name: 'github', repo: 'owner/repo' },
collections: [/* ... */],
};
影响 : 仅影响 TypeScript 用户。类型导入的破坏性变更。
新功能 :
CmsConfig 类型供直接 TypeScript 导入新功能 : 在字段级别覆盖 media_folder (而不仅仅是集合级别)。
用法 :
collections:
- name: posts
label: Blog Posts
folder: content/posts
media_folder: static/images/posts # 集合级别默认值
fields:
- label: Featured Image
name: image
widget: image
media_folder: static/images/featured # ← 字段级别覆盖
public_folder: /images/featured
- label: Author Avatar
name: avatar
widget: image
media_folder: static/images/avatars # ← 另一个覆盖
public_folder: /images/avatars
使用场景 : 同一集合中不同类型图像使用不同的媒体文件夹。
弃用 : logo_url 选项现已弃用。迁移到 logo.src。
迁移 :
# ❌ 已弃用
logo_url: https://yourdomain.com/logo.svg
# ✅ 新方式 (v0.113.5+)
logo:
src: https://yourdomain.com/logo.svg
破坏性变更 : Markdown 小部件的 sanitize_preview 默认值更改为 true (防止 XSS)。
影响 :
sanitize_preview: false (与 Netlify/Decap CMS 兼容,但易受 XSS 攻击)sanitize_preview: true (默认安全)迁移 :
collections:
- name: posts
fields:
- label: Body
name: body
widget: markdown
sanitize_preview: false # ← 仅在信任所有 CMS 用户时添加
建议 : 保持默认值 (true),除非禁用可以修复损坏的预览并且您完全信任所有 CMS 用户。
全局配置 slug 生成行为:
slug:
encoding: unicode-normalized
clean_accents: false
sanitize_replacement: '-'
lowercase: true # 默认:转换为小写 (v0.128.0+)
maxlength: 50 # 默认:无限制 (v0.127.0+)
lowercase (v0.128.0+): 设置为 false 以在 slug 中保留原始大小写 (例如,"MyBlogPost" 而不是 "myblogpost")。
使用场景 : 大小写混合的 URL 或文件名,其中大小写很重要。
来源 : 发布 v0.128.0, GitHub Issue #594
新的 raw 格式允许编辑没有 front matter 的文件 (CSV、JSON、YAML、纯文本)。必须有一个名为 body 的字段,小部件类型为:code、markdown、richtext 或 text。
使用场景 :
配置 :
collections:
- name: config
label: Configuration Files
files:
- label: Site Config
name: site_config
file: config.json
format: raw # ← 新格式类型
fields:
- label: Config
name: body
widget: code
default_language: json
限制 :
body)code、markdown、richtext 或 text来源 : 发布 v0.126.0
数字字段的新 value_type 选项接受 int/string 和 float/string,以将数字保存为字符串而不是 front matter 中的数字。
使用场景 : 某些静态站点生成器或模式要求将数值存储为字符串 (例如,age: "25" 而不是 age: 25)。
配置 :
fields:
- label: Age
name: age
widget: number
value_type: int/string # 保存为 "25" 而不是 25
- label: Price
name: price
widget: number
value_type: float/string # 保存为 "19.99" 而不是 19.99
来源 : 发布 v0.125.0, GitHub Issue #574
通过 URL 查询参数 ?_locale=fr 覆盖编辑器区域设置,以获取特定区域设置的编辑链接。
使用场景 : 为翻译人员或内容编辑人员生成特定语言的直接编辑链接。
示例 :
https://yourdomain.com/admin/#/collections/posts/entries/my-post?_locale=fr
来源 : 发布 v0.126.0, GitHub Issue #585
添加了 richtext 作为 markdown 小部件的别名,以与 Decap CMS 术语保持一致。两者功能相同。
配置 :
fields:
- label: Body
name: body
widget: richtext # ← markdown 的新别名
未来计划 : 计划为 richtext 字段类型添加 HTML 输出支持。
来源 : 发布 v0.124.0
所有框架都遵循相同的模式:
在 public/static 文件夹中创建 admin 目录:
static/admin/admin/admin/ (使用 passthrough copy)public/admin/public/admin/创建 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>
3. 创建 admin/config.yml:
backend:
name: github
repo: owner/repo
branch: main
base_url: https://your-worker.workers.dev # OAuth 代理 (必需)
media_folder: static/images/uploads # 框架特定路径
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' }
4. 访问 admin: http://localhost:<port>/admin/
框架特定细节 : 查看 templates/ 目录获取完整示例。
为什么使用 Cloudflare Workers : 最快,提供免费套餐,适用于任何部署平台。
步骤:
部署 Worker:
git clone https://github.com/sveltia/sveltia-cms-auth cd sveltia-cms-auth npm install npx wrangler deploy
在 GitHub 上注册 OAuth 应用:
https://your-worker.workers.dev/callback配置 Worker 环境变量:
npx wrangler secret put GITHUB_CLIENT_ID # 粘贴您的 Client ID
npx wrangler secret put GITHUB_CLIENT_SECRET
# 粘贴您的 Client Secret
4. 更新 CMS 配置:
backend:
name: github
repo: owner/repo
branch: main
base_url: https://your-worker.workers.dev # ← 添加此行
5. 测试身份验证:
* 打开 `/admin/`
* 点击 "Login with GitHub"
* 应重定向到 GitHub → 授权 → 返回 CMS
替代方案 : Vercel 无服务器函数 - 查看 templates/vercel-serverless/
此技能可防止设置 Sveltia CMS 时遇到的 10 个常见错误。
错误消息:
https://api.netlify.com/auth 而不是 GitHub 登录症状:
原因:
base_url解决方案:
步骤 1:验证 config.yml 是否有 base_url:
backend:
name: github
repo: owner/repo
branch: main
base_url: https://your-worker.workers.dev # ← 必须存在
步骤 2:检查 GitHub OAuth 应用回调:
https://your-worker.workers.dev/callbackhttps://yourdomain.com/callback步骤 3:直接测试 Worker:
curl https://your-worker.workers.dev/health
# 应返回:{"status": "ok"}
错误消息:
+++ 分隔符症状:
原因:
解决方案:
使用 YAML 而不是 TOML (推荐):
collections:
- name: posts
folder: content/posts
format: yaml # 或 md (带 YAML frontmatter 的 Markdown)
# 不要用:format: toml
如果必须使用 TOML:
错误消息:
症状:
原因:
解决方案:
步骤 1:验证 YAML:
pip install yamllint
find content -name "*.md" -exec yamllint {} \;
步骤 2:常见修复:
问题 : 智能引号
# ❌ 错误 - 从复制粘贴中获取的智能引号
title: "Hello World" # 花引号
# ✅ 正确 - 直引号
title: "Hello World" # 直引号
步骤 3:使用 yamlfmt 自动修复:
go install github.com/google/yamlfmt/cmd/yamlfmt@latest
find content -name "*.md" -exec yamlfmt {} \;
错误消息:
症状:
原因:
解决方案:
步骤 1:验证文件夹路径:
# 配置指定:
collections:
- name: posts
folder: content/posts # 期望文件在此处
# 检查实际位置:
ls -la content/posts # 文件必须存在于此
步骤 2:使格式与实际文件匹配:
# 如果文件是:content/posts/hello.md 带 YAML frontmatter
collections:
- name: posts
folder: content/posts
format: yaml # 或 md (对于 .md 文件与 yaml 相同)
错误消息:
Uncaught ReferenceError: SVELTIA is not defined症状:
原因:
type="module" 属性解决方案:
使用正确的 script 标签:
<!-- ✅ 正确 -->
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
<!-- ❌ 错误 - 缺少 type="module" -->
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
使用版本锁定 (推荐):
<script src="https://unpkg.com/@sveltia/cms@0.128.5/dist/sveltia-cms.js" type="module"></script>
错误消息:
/admin/ 时出现 "404 Not Found"症状:
原因:
解决方案:
框架特定修复:
Hugo : static/ 中的文件会自动复制
Jekyll : 添加到 _config.yml:
include:
- admin
11ty : 添加到 .eleventy.js:
module.exports = function(eleventyConfig) {
eleventyConfig.addPassthroughCopy('admin');
};
Astro : public/ 中的文件会自动复制
错误消息:
症状:
原因:
解决方案:
在 iPhone 上:
或启用图像优化:
media_libraries:
default:
config:
max_file_size: 10485760 # 10 MB
transformations:
raster_image:
format: webp # 自动转换为 WebP
quality: 85
错误消息:
症状:
原因:
format 时,Sveltia 变得严格 - 具有不同格式的现有条目显示为空白⚠️ 严重:格式严格性警告 (v0.124.1+)
指定 format 选项时,Sveltia 变得严格:
解决方案:
选项 1:使用 picker_utc (推荐)
fields:
- label: Date
name: date
widget: datetime
picker_utc: true # 最灵活 - 输出带时区
选项 2:指定带时区的格式 (有风险 - 参见上方警告)
fields:
- label: Date
name: date
widget: datetime
format: "YYYY-MM-DDTHH:mm:ss.SSSZ" # 仅当所有现有日期都匹配此格式时使用
选项 3:配置 Hugo 以接受缺少时区的情况
# config.toml
[frontmatter]
date = [":default", ":fileModTime"]
预防措施 :
formatformat 之前先规范化所有日期picker_utc: true (更灵活)来源 : GitHub Issue #565,在 v0.126.0 中修复 (改进了日期解析器,但格式严格性仍然存在)
错误消息:
症状:
原因:
⚠️ 影响 : 对欧盟公共部门和注重隐私的网站构成阻碍性问题
解决方案 (Vite 插件 - 推荐) :
// 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()],
})
替代解决方案 :
选项 2:Bunny Fonts (1:1 Google Fonts 替代品)
选项 3:自托管字体
@fontsource npm 包维护者回应 :
来源 : GitHub Issue #443
错误消息:
症状:
原因:
Cross-Origin-Opener-Policy 头阻止了 OAuth解决方案:
Cloudflare Pages (_headers 文件):
/*
Cross-Origin-Opener-Policy: same-origin-allow-popups
# 不要用:same-origin (这会破坏 OAuth)
Netlify (_headers 文件):
/*
Cross-Origin-Opener-Policy: same-origin-allow-popups
Vercel (vercel.json):
{
"headers": [
{
"source": "/(.*)",
"headers": [
{
"key": "Cross-Origin-Opener-Policy",
"value": "same-origin-allow-popups"
}
]
}
]
}
这些问题存在于早期版本中,但现已修复。此处记录以供参考。
问题 : 当 path 选项包含括号 () 时,Sveltia CMS 无法加载现有条目。这影响了使用路由组如 app/(content)/(writing)/ 的 Next.js/Nextra 用户。
症状 (v0.128.1 之前):
失败的示例 :
collections:
- name: pages
folder: app/(pages)
path: "{{slug}}/page" # ← 无法加载现有条目
extension: mdx
状态 : 已在 v0.128.1 中修复 (2026年1月13日)
来源 : GitHub Issue #596
问题 : 带有 folder: "" 或 folder: "." 或 folder: "/" 的集合在通过 GitHub 后端创建新条目时失败。GraphQL 查询错误地构造了以 / 开头 (绝对) 而不是相对路径的路径。
症状 (v0.125.0 之前):
失败的示例 :
collections:
- name: root-pages
folder: "" # 或 "." 或 "/"
# ← 通过 GitHub 后端创建条目时破坏
使用场景 : VitePress 和其他在仓库根目录存储内容的框架。
状态 : 已在 v0.125.0 中修复 (2025年12月20日)
来源 : GitHub Issue #580
Sveltia CMS 是 Decap CMS 的直接替代品。
步骤 1:更新 script 标签 (更改 1 行):
<!-- 旧: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@0.128.5/dist/sveltia-cms.js" type="module"></script>
步骤 2:保留现有 config.yml (无需更改)
步骤 3:本地测试 (验证登录、内容列表、编辑、保存)
就这样! 您的内容、集合和工作流程保持不变。
不支持 :
变通方案 : 改用 Cloudflare Workers 或 Vercel OAuth 代理。
注意 : 官方文档站点正在积极开发中。对于某些主题,GitHub README 仍然是一个有用的备用资源。
预计节省 : 65-70% (~6,300 个令牌)
无技能 (~9,500 个令牌):
有技能 (~3,200 个令牌):
此技能可防止 10 个常见错误 (100% 预防率):
最后更新 : 2026-01-21 技能版本 : 2.1.0 Sveltia CMS 版本 : 0.128.5 (测试版) 状态 : 生产就绪,v1.0 正式版预计 2026 年初 变更 : 添加了 6 个新配置选项 (slug 小写、原始格式、数字字符串编码、区域设置 URL 参数、富文本别名、Gemini 2.5 Flash-Lite 支持),更新了日期时间错误并添加了格式严格性警告,添加了 GDPR Google Fonts 变通方案,记录了 2 个已修复的历史问题,弃用了 slug_length 选项
每周安装
302
仓库
GitHub 星标
643
首次出现
Jan 20, 2026
安全审计
安装于
claude-code255
gemini-cli203
opencode199
cursor191
antigravity184
codex175
Complete skill for integrating Sveltia CMS into static site projects.
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
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 nameUsage :
fields:
- label: Author Email
name: author_email
widget: hidden
default: '{{author-email}}'
Commit message templates also support {{author-email}} tag.
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.
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.
New Features :
CmsConfig type for direct TypeScript importNew 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.
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
BREAKING : sanitize_preview default changed to true for Markdown widget (XSS prevention).
Impact :
sanitize_preview: false (compatibility with Netlify/Decap CMS, but vulnerable to XSS)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.
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
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 :
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 :
body)code, markdown, richtext, or textSource : Release v0.126.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
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
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
All frameworks follow the same pattern:
Create admin directory in public/static folder:
static/admin/admin/admin/ (with passthrough copy)public/admin/public/admin/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>
3. 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' }
4. Access admin: http://localhost:<port>/admin/
Framework-specific details : See templates/ directory for complete examples.
Why Cloudflare Workers : Fastest, free tier available, works with any deployment platform.
Steps:
Deploy Worker:
git clone https://github.com/sveltia/sveltia-cms-auth cd sveltia-cms-auth npm install npx wrangler deploy
Register OAuth App on GitHub:
https://your-worker.workers.dev/callbackConfigure 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
4. Update CMS config:
backend:
name: github
repo: owner/repo
branch: main
base_url: https://your-worker.workers.dev # ← Add this line
5. Test authentication:
* Open `/admin/`
* Click "Login with GitHub"
* Should redirect to GitHub → Authorize → Back to CMS
Alternative : Vercel serverless functions - See templates/vercel-serverless/
This skill prevents 10 common errors encountered when setting up Sveltia CMS.
Error Message:
https://api.netlify.com/auth instead of GitHub loginSymptoms:
Causes:
base_url in backend configSolution:
Step 1: Verify config.yml hasbase_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:
https://your-worker.workers.dev/callbackhttps://yourdomain.com/callbackStep 3: Test Worker directly:
curl https://your-worker.workers.dev/health
# Should return: {"status": "ok"}
Error Message:
+++ delimitersSymptoms:
Causes:
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:
Error Message:
Symptoms:
Causes:
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 {} \;
Error Message:
Symptoms:
Causes:
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)
Error Message:
Uncaught ReferenceError: SVELTIA is not definedSymptoms:
Causes:
type="module" attributeSolution:
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>
Error Message:
/admin/Symptoms:
Causes:
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
Error Message:
Symptoms:
Causes:
Solution:
On iPhone:
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
Error Message:
Symptoms:
Causes:
format is specified, Sveltia becomes strict - existing entries with different formats show as blank⚠️ CRITICAL: Format Strictness Warning (v0.124.1+)
When you specify a format option, Sveltia becomes strict :
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 :
format if you have mixed date formatsformatpicker_utc: true instead (more flexible)Source : GitHub Issue #565, fixed in v0.126.0 (improved date parser but format strictness remains)
Error Message:
Symptoms:
Causes:
⚠️ 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)
Option 3: Self-hosted fonts
@fontsource npm packagesMaintainer Response :
Source : GitHub Issue #443
Error Message:
Symptoms:
Causes:
Cross-Origin-Opener-Policy header blocking OAuthSolution:
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"
}
]
}
]
}
These issues were present in earlier versions but have been fixed. Documented here for reference.
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):
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
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):
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
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 :
Workaround : Use Cloudflare Workers or Vercel OAuth proxy instead.
Note : The official documentation site is being actively developed. GitHub README remains a useful fallback for some topics.
Estimated Savings : 65-70% (~6,300 tokens saved)
Without Skill (~9,500 tokens):
With Skill (~3,200 tokens):
This skill prevents 10 common errors (100% prevention rate):
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
Weekly Installs
302
Repository
GitHub Stars
643
First Seen
Jan 20, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
claude-code255
gemini-cli203
opencode199
cursor191
antigravity184
codex175
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
106,200 周安装