🔗 Related cheat sheets:
- 🧱 Sveltia + Hugo: sveltia-hugo.md
- 🚀 Hugo core: hugo.md
- 🧾 Hugo Markdown: hugo_markdown.md
- 🎨 Hugo themes & addons: hugo_themes-and-addons.md
Goal: modern Git-based CMS, mostly drop-in for Netlify/Decap CMS.
🚦 When to use Sveltia
- You already use Netlify/Decap CMS and want:
- Faster, lighter UI and better UX
- Better i18n, widgets, collections
- Improved accessibility and mobile support
- You want a Git-based CMS that works with:
- Hugo, Eleventy, Astro, SvelteKit, Next.js, etc.
- You are comfortable editing a config file in your repo.
Docs: https://github.com/sveltia/sveltia-cms
⚙️ Install and migration basics
Two main ways to load Sveltia CMS:
- CDN script in /admin/index.html (simplest)
- Typical migration from Netlify/Decap CMS:
<!-- /static/admin/index.html -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Sveltia CMS</title>
<script
src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"
onload="SVELTIA.start()"
onerror="document.body.innerHTML='Failed to load Sveltia CMS'"
></script>
<link href="/admin/config.yml" type="application/yaml" rel="cms-config-url" />
</head>
<body></body>
</html>- Migrating from Netlify CMS (decapcms.org syntax): just replace the script tag.
-<script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
+<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>- Migrating from Decap CMS:
-<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
+<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>- npm package (for bundler/manual init flows)
- Install:
npm i @sveltia/cms
# or
pnpm add @sveltia/cms- If you previously used decap-cms-app:
-import CMS, { init } from 'decap-cms-app'
+import CMS, { init } from '@sveltia/cms'The manual initialization flow (calling init, registering widgets, etc.) mirrors Decap CMS.
🧾 Config file overview
Sveltia CMS intentionally keeps the same config model as Netlify/Decap CMS.
Default file and location examples:
- static/admin/config.yml
- public/admin/config.yml
Core sections:
backend:
name: github
repo: yourusername/yourrepo
branch: main
# base_url: https://your-auth-proxy.example # for external OAuth
media_folder: "static/uploads"
public_folder: "/uploads"
collections:
- name: blog
label: Blog Posts
folder: content/blog
create: true
slug: "{{slug}}"
extension: "md"
format: "yaml"
fields:
- { name: title, label: Title, widget: string }
- { name: date, label: Date, widget: datetime }
- { name: description, label: Description, widget: text, required: false }
- { name: tags, label: Tags, widget: list, required: false }
- { name: body, label: Body, widget: markdown }Key ideas:
- backend: how Sveltia talks to Git (GitHub, GitLab, Gitea, Forgejo) and where.
- media_folder: where uploaded files go in the repo.
- public_folder: how those files are referenced from rendered HTML.
- collections: define what content types editors can create and edit.
Config reference (same as Decap CMS):
- Options: https://decapcms.org/docs/configuration-options/
- Widgets: https://decapcms.org/docs/widgets/
🌍 Backends and authentication
Supported Git backends (at time of writing):
- GitHub
- GitLab
- Gitea/Forgejo
Not supported:
- Git Gateway (Netlify Identity). You must migrate to a Git backend.
Common auth patterns:
-
Netlify-hosted or Netlify-auth-powered sites
- Use GitHub or GitLab backend.
- Netlify’s api.netlify.com can still facilitate OAuth.
-
Non-Netlify hosts (GitHub Pages, Cloudflare Pages, custom)
- Use Sveltia’s own OAuth client:
- https://github.com/sveltia/sveltia-cms-auth
- Deploy to Cloudflare Workers or similar.
- Set backend.base_url to your auth worker URL.
- Or use a personal access token (PAT) for technical users.
- Use Sveltia’s own OAuth client:
🧠 Config formats: YAML, JSON, TOML
Sveltia CMS can read config files in multiple formats.
- YAML (classic Netlify/Decap style)
<link href="/admin/config.yml" type="application/yaml" rel="cms-config-url" />- JSON (good for programmatic generation)
<link href="/admin/config.json" type="application/json" rel="cms-config-url" />- TOML (less common, but supported)
<link href="/admin/config.toml" type="application/toml" rel="cms-config-url" />You can also pass a JS object when using manual init.
🧩 JSON schema and editor integration
To get autocomplete and validation while editing the config, Sveltia provides a JSON schema:
Schema URL:
Examples:
- YAML config with VS Code YAML extension:
# yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json
backend:
name: github- TOML config with Even Better TOML extension:
#:schema https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json
backend.name = "github"- JSON config:
{
"$schema": "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json",
"backend": { "name": "github" }
}📚 Collections: folder, file, and singletons
Standard folder collection:
collections:
- name: posts
label: Blog posts
folder: content/posts
create: true
slug: "{{slug}}"
extension: "md"
format: "yaml"
fields:
- { name: title, label: Title, widget: string }
- { name: date, label: Date, widget: datetime }
- { name: body, label: Body, widget: markdown }Including Hugo-style _index.md with index_file (works nicely with Hugo sections):
collections:
- name: posts
label: Blog posts
folder: content/posts
fields:
- { name: title, label: Title }
- { name: date, label: Published Date, widget: datetime }
- { name: description, label: Description }
- { name: body, label: Body, widget: markdown }
index_file:
fields:
- { name: title, label: Title }
- { name: body, label: Body, widget: markdown }Singletons: great for site settings, home page data, etc.
singletons:
- name: home
label: Home Page
file: content/home.yaml
icon: home
fields: ...
- divider: true
- name: settings
label: Site Settings
file: content/settings.yaml
icon: settings
fields: ...If you need to reference a singleton from a relation field, use collection: _singletons.
🎛️ Widgets and editor UX
Sveltia CMS reuses and extends the Decap CMS widget set.
- Common widgets: string, text, markdown, datetime, boolean, list, relation, select.
- Extra improvements around:
- UUID and IDs
- Localized fields and slugs
- Better asset management
Keyboard shortcuts (desktop):
- Alt+1: Content library
- Alt+2: Asset library
- Ctrl+F / Command+F: Search entries and assets
- Ctrl+E / Command+E: New entry
- Ctrl+S / Command+S: Save
- Escape: Cancel editing
🧪 Practical tips
- Start with a pure YAML config unless you really need TOML or JSON.
- Keep collections simple and expand with widgets only when the content model stabilizes.
- Use index_file for frameworks with special index files (like Hugo’s _index.md).
- Use singletons for global settings and home pages instead of ad-hoc file collections.
- Enable JSON schema in your editor early; it catches typos and invalid options.
⚠️ Gotchas
- Git Gateway is not supported; use GitHub, GitLab, Gitea, or Forgejo backends.
- Some Netlify/Decap features are not implemented or intentionally not planned; check the current limitations in the README before migrating.
- Front matter formatting must be valid for the selected format:
- YAML: single document, balanced quotes, no extra --- markers in the body.
- TOML: requires proper +++ delimiters and separation of body content.
- When switching a project from TOML to YAML (or vice versa), update both:
- Existing content files
- CMS config (format) and your static site generator config.
- If SVELTIA is not defined in the browser console, double-check the script src, network errors, and that the CMS script is loaded before calling SVELTIA.start().