Configuration Basics
This guide covers the basics of configuring Sveltia CMS using a configuration file. It explains the supported file formats, how to specify the configuration file location and how to enable validation and autocomplete in your code editor.
Future Plans
We plan to introduce a graphical configuration editor in a future release, allowing users to create and modify the configuration directly within the CMS interface. For now, please refer to this guide for manual configuration.
Compatibility with Other Platforms
Netlify CMS and Decap CMS
Sveltia CMS is designed to be compatible with Netlify/Decap CMS configuration files. In most cases, your existing config.yml file from Netlify/Decap CMS works with Sveltia CMS as is. However, some options may have been deprecated or replaced in Sveltia CMS, so review the configuration file and make any necessary adjustments. See the migration guide for details.
Pages CMS
Pages CMS was inspired by Netlify CMS and shares a similar configuration structure. The .pages.yml file can’t be used as is, but most of its options have a direct equivalent in Sveltia CMS. See the migration guide for how to convert it. There are also AI tools available to assist with this process.
Supported Formats
Sveltia CMS supports configuration files in the following formats:
YAML
The CMS configuration file is usually written in YAML format. Ensure that your file adheres to proper YAML syntax to avoid parsing errors. If you are new to YAML, consider reviewing a YAML tutorial to familiarize yourself with the syntax.
Sveltia CMS currently uses the yaml npm package for parsing and serializing YAML files.
Here are some key YAML syntax features to keep in mind:
Comments
YAML supports comments using the # symbol. Comments can be placed on their own line or at the end of a line:
# This is a comment
title: My Site # This is an inline commentShorthand Notation
Sometimes we use shorthand notation for brevity. For example,
fields:
- name: title
label: Title
widget: string
- name: align
label: Alignment
widget: select
options:
- left
- center
- rightis the same as
fields:
- { name: title, label: Title, widget: string }
- { name: align, label: Alignment, widget: select, options: [left, center, right] }Quoting Strings
In YAML, strings can be quoted using single (') or double (") quotes. Quoting is necessary when the string contains special characters, leading/trailing spaces or when you want to preserve the exact formatting. For example:
description: 'A site with special characters: #, :, -'Multiline Strings
YAML allows multiline strings using the | (literal) or > (folded) indicators. For example:
description: |
This is a multiline
string that preserves
line breaks.
summary: >
This is a folded multiline string that replaces line breaks with spaces.Anchors and Aliases
YAML supports anchors and aliases to reuse configuration snippets. This is an advanced feature that can help reduce duplication. For example:
fields:
- &title_field
name: title
label: Title
widget: string
- name: subtitle
label: Subtitle
widget: string
- <<: *title_field
name: headline
label: HeadlineTOML
TOML format is also supported for configuration files. If you prefer TOML, create a file named config.toml instead of config.yml and write the configuration in TOML syntax. Make sure to add a <link> tag in your HTML to point to the file with the correct MIME type (see the Config URL section below).
Sveltia CMS currently uses the smol-toml npm package for parsing and serializing TOML files.
JSON
Sveltia CMS also supports JSON format for configuration files. However, JSON is mainly intended for programmatic generation of configuration files rather than manual editing, due to its verbosity and lack of support for comments.
To use a JSON configuration file, create a file named config.json instead of config.yml and write the configuration in JSON syntax. Then add a <link> tag in your HTML to point to the file with the correct MIME type (see the Config URL section below).
We don’t support JSONC, JSON5 or other JSON variants — only standard JSON that can be parsed by JSON.parse and serialized by JSON.stringify. If you want to write comments in your configuration file, use YAML format instead.
JavaScript/TypeScript
Instead of using a static configuration file, you can also provide the CMS configuration as a JavaScript object when manually initializing the CMS. It gives you the most flexibility and control over the configuration, allowing you to dynamically generate or modify the configuration based on your application logic.
The field configuration for custom editor components also uses JavaScript objects.
Config URL
You can customize the configuration file location and format by specifying a URL in your HTML using a <link> tag with rel="cms-config-url". This is useful if you want to store the configuration file in a different location or use a different format than the default.
Configuration is Public
Regardless of the location, the configuration file is publicly accessible on the web server. Avoid including sensitive information, such as API keys or passwords, in the configuration file.
Custom Configuration File Path
By default, Sveltia CMS looks for a YAML configuration file named config.yml located in the same folder as the index.html file. The file is typically accessible at /admin/config.yml on a web server. There is no need to specify this default location explicitly.
To specify a custom configuration file path, add a <link> tag in your HTML’s <head> section:
<link href="/cms/config.yaml" type="application/yaml" rel="cms-config-url" />The MIME type for YAML files is application/yaml (standardized), or text/yaml or application/x-yaml (legacy). All of them are supported.
TOML or JSON Configuration File
If you use a TOML or JSON configuration file instead of YAML, you need to add a <link> tag with the appropriate MIME type. This tells Sveltia CMS to load the configuration from the specified file instead of the default config.yml. Below are examples for both formats.
<link href="/admin/config.toml" type="application/toml" rel="cms-config-url" /><link href="/admin/config.json" type="application/json" rel="cms-config-url" />Multiple Configuration Files
You can specify multiple configuration files by adding multiple <link> tags. Sveltia CMS will merge them in the order they appear in the HTML.
<link href="/admin/config.yml" type="application/yaml" rel="cms-config-url" />
<link href="/admin/collections/authors.yml" type="application/yaml" rel="cms-config-url" />
<link href="/admin/collections/pages.yml" type="application/yaml" rel="cms-config-url" />
<link href="/admin/collections/posts.yml" type="application/yaml" rel="cms-config-url" />Limitations
YAML anchors, aliases and merge keys only work if they are in the same file. This is because the files are parsed as separate JavaScript objects and then merged using the @fastify/deepmerge library.
Also, modularized configuration files may raise errors if you enable JSON schema validation in your code editor, as the schema expects a complete configuration object.
Validation and Autocomplete
For a better development experience, Sveltia CMS provides JSON schema support and TypeScript types for configuration validation and autocomplete.
JSON Schema
Sveltia CMS provides a full JSON schema for the configuration file, so you can get autocomplete and validation in your favorite code editor while editing the CMS configuration. The schema is generated from the source and always up to date with the latest CMS version.
Enabling JSON Schema Validation in VS Code
If you use VS Code, you can enable it for the YAML configuration file by installing the YAML extension and adding the following comment to the top of config.yml:
# yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.jsonFor TOML files, install the Even Better TOML extension and add the following comment to the top of config.toml:
#:schema https://unpkg.com/@sveltia/cms/schema/sveltia-cms.jsonJSON files have native support in VS Code, so no extension is needed. Just add the following line to the top of config.json, within the curly braces:
"$schema": "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json",Workspace-level configuration
Instead of adding the schema comment to the top of the configuration file, you can also set it up at the workspace level in VS Code. Add the following to your project’s VS Code settings file at .vscode/settings.json, within the outer curly braces.
For YAML files:
"yaml.schemas": {
"https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json": ["/public/admin/config.yml"]
}For JSON files:
"json.schemas": [
{
"fileMatch": ["/public/admin/config.json"],
"url": "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json"
}
]The configuration file location varies by framework and project structure, so adjust the path accordingly. For example, if you use Hugo, the file is typically located in the /static/admin/ directory.
Updating the Schema
VS Code caches the schema file and will not update it automatically when a new version of the CMS is released. To update the schema locally, reload your project’s editor by pressing Ctrl+Shift+P (Windows/Linux) or Command+Shift+P (macOS) and selecting “Developer: Reload Window.” Alternatively, relaunch VS Code.
Other Editors
Check your code editor or IDE documentation to see if it supports JSON schema validation for YAML, TOML or JSON files. If supported, use the following schema URL:
https://unpkg.com/@sveltia/cms/schema/sveltia-cms.jsonWebStorm and other JetBrains IDEs have built-in support for JSON schema validation in YAML and JSON files. You can configure the schema in the IDE settings.
TypeScript Support
When using the @sveltia/cms package in a TypeScript-enabled project, you can get type checking and autocomplete for the API, including the configuration object when manually initializing the CMS.
The type definitions are generated from the JSDoc comments in the source code, ensuring they are accurate and up to date with the latest CMS version.
Runtime Validation
Sveltia CMS validates the configuration every time it loads. Anything that would break the CMS is listed on the login screen, and users can’t sign in until it’s fixed. This way, a broken configuration never reaches the content editor. Everything the CMS can safely work around is logged to the browser console as a warning instead.
Each message names the collection, file and field it applies to, so you can go straight to the line that needs changing:
Blog collection,
seo.scorefield: Theminoption must be a number.
Two sets of checks run. The first validates the whole configuration against the same JSON schema your editor uses, published alongside the CMS version you’re running. It catches wrong value types, values outside an allowed set and missing required options.
A custom field type registered with its own schema joins these checks, so the options it accepts are validated alongside the built-in ones.
The second set covers the rules a schema can’t express. Most of these mistakes wouldn’t fail at all otherwise. Instead, they would quietly give you an empty collection, a random slug or a validation rule that never runs:
- Backend:
- a missing, unsupported or misspelled backend name, with a pointer to the supported backends
- a missing
repo, or one that isn’t in theowner/repoformat - a missing OAuth client ID (
app_id) for GitLab PKCE or Gitea/Forgejo - the unsupported implicit flow
- an empty
auth_methodslist, which would leave no way to sign in - Open Authoring without Editorial Workflow or without an
auth_scope
- Site-wide options:
- a
site_urlthat isn’t an absolute URL, which would silently drop every preview link - a missing
media_folder, or apublic_folderthat isn’t an absolute path - template tags in the top-level
media_folder, which can’t be resolved without an entry - a
sanitize_replacementslug option that itself contains a character slugs can’t have (other than a plain space) - an empty
i18n.localeslist - a
default_localeorinitial_localesentry that isn’t one of thelocales - a collection or file
i18noption with no site-level i18n to build on
- a
- Internationalization — an
i18noption that leaves nothing to translate:- a site-level configuration that no collection or singleton enables with its own
i18noption - an entry collection or collection file with i18n enabled but no field with
i18n: true(ortranslate) ori18n: duplicate - a file collection with i18n enabled but none of its files
- a site-level configuration that no collection or singleton enables with its own
- Collections:
- duplicate, empty or invalid collection, file, field and variable type names (e.g. names containing
.or*, or the reserved name__proto__) - a collection with none of
folder,filesordivider, or more than one of them - a collection without fields
- a configuration where every collection is hidden
- a mismatch between
formatandextension - a
bodyfield that can’t hold text in a front matter format, as the file body is plain text - a template tag that a collection or field
media_folderorpublic_folderdoesn’t support - a
{{locale}}placeholder in a file path without i18n
- duplicate, empty or invalid collection, file, field and variable type names (e.g. names containing
- Entry naming:
- an
identifier_fieldthat names no field - a collection with neither a
titlefield nor anidentifier_fieldorslugoption - a
slugtemplate containing slashes slug,path,summary,thumbnailandpreview_pathoptions that refer to fields that don’t exist, or that use date tags without a DateTime field to read them from
- an
- Entry lists:
- a
filteron an undefined field, with neither avaluenor apattern, or with a pattern that isn’t a valid regular expression sortable_fields,view_groupsandview_filtersthat refer to undefined fields- a
view_groupsorview_filtersdefaultthat names no group or filter - a
reordergroup that isn’t defined table_columnsorsummary_fieldsthat refer to undefined fieldsbulk_editfields that aren’t defined at the top level or can’t be edited in bulk
- a
- Fields:
- widget-specific options, such as a
search_fieldslist written as a string - mutually exclusive options, such as
field,fieldsandtypeson List fields - an explicitly empty
fieldsortypeslist on a List or Object field (omittingfieldsin a variable type remains valid) - a validation
patternthat isn’t a valid regular expression - a
minabove themax, or aminlengthabove themaxlength - a Number
stepof zero or less - Select fields with no options or duplicate option values
- conflicting DateTime timezone options, or an invalid IANA timezone identifier
- widget-specific options, such as a
- Default values — a
defaultwhose shape doesn’t match the field’s other options:- a Select
defaultthat isn’t among theoptions - a Select, Relation, File or Image
defaultthat is an array withoutmultiple, or a single value with it - a Number
defaultthat isn’t a number of thevalue_type - a Code
defaultobject withoutput_code_only, or with a property that isn’t one of thekeys - a List or Object
defaultwith an object where a plain value is expected or the other way round, a property that names no subfield, or a missing or unknown variable type
- a Select
- References between fields:
- a Relation field whose
collectionorfiledoesn’t exist, or whosevalue_field,display_fields,search_fieldsorfiltersname fields the referenced collection doesn’t have - a Compute
valuetemplate that names an undefined field - a List or Object
thumbnailthat names an undefined subfield, or one that isn’t an Image or File field
- a Relation field whose
- Options that Sveltia CMS doesn’t support, including deprecated camel case options such as
valueField, the deprecated Date widget and other unsupported widgets
Unknown Options
An option name the schema doesn’t define is a warning rather than an error. This way, a configuration carrying leftovers from Netlify/Decap CMS — or options from a newer release — keeps working. The option has no effect, and the console says so:
Blog collection: The
filter.Tutorialoption is not defined in the Sveltia CMS configuration schema. It will be ignored. Check for a typo or a syntax mistake.
A misspelled name is the obvious way to get one of these, but not the only one. That’s why the console is worth a look whenever an option seems to do nothing. For example, a YAML flow mapping quietly turns a comma-separated list into extra keys:
# `Tutorial` becomes an option of its own, and only `News` is matched
filter: { field: category, value: News, Tutorial }
# What was meant, with `value` holding both values
filter: { field: category, value: [News, Tutorial] }Editor validation is still worth setting up
JSON schema validation in your editor reports an unknown option as you type, before the CMS ever loads the file.