--- url: /en/docs/config-basics.md description: >- Configure Sveltia CMS using YAML, TOML, JSON, or JavaScript with schema validation, autocomplete, and runtime checks. --- # 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. ::: info 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. You can use your existing `config.yml` file from Netlify/Decap CMS with Sveltia CMS, and it should work without any issues in most cases. However, please note that some options may have been deprecated or replaced in Sveltia CMS, so it’s recommended to review the configuration file and make any necessary adjustments. See the [migration guide](/en/docs/migration/netlify-decap-cms) 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](/en/docs/migration/pages-cms) for how to convert it. There are also [AI tools](/en/docs/working-with-ai) 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](https://www.redhat.com/en/topics/automation/what-is-yaml) to familiarize yourself with the syntax. Sveltia CMS currently uses the [`yaml` npm package](https://www.npmjs.com/package/yaml) 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: ```yaml # This is a comment title: My Site # This is an inline comment ``` #### Shorthand Notation Sometimes we use shorthand notation for brevity. For example, ```yaml fields: - name: title label: Title widget: string - name: align label: Alignment widget: select options: - left - center - right ``` is the same as ```yaml 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: ```yaml description: 'A site with special characters: #, :, -' ``` #### Multiline Strings YAML allows multiline strings using the `|` (literal) or `>` (folded) indicators. For example: ```yaml 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: ```yaml fields: - &title_field name: title label: Title widget: string - name: subtitle label: Subtitle widget: string - <<: *title_field name: headline label: Headline ``` ### TOML 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 `` tag in your HTML to point to the file with the correct MIME type (see the [Config URL](#toml-or-json-configuration-file) section below). Sveltia CMS currently uses the [`smol-toml` npm package](https://www.npmjs.com/package/smol-toml) 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, and add a `` tag in your HTML to point to the file with the correct MIME type (see the [Config URL](#toml-or-json-configuration-file) section below). We don’t support JSONC, JSON5, or other JSON variants — only standard JSON that can be parsed by [`JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) and serialized by [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](/en/docs/api/initialization) 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](/en/docs/api/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 `` 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. ::: warning 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 `` tag in your HTML’s `` section: ```html ``` The MIME type for YAML files is `application/yaml` (standardized) or `text/yaml` (legacy). Both are supported. ### TOML or JSON Configuration File If you use a TOML or JSON configuration file instead of YAML, you need to add a `` 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. ```html ``` ```html ``` ### Multiple Configuration Files You can specify multiple configuration files by adding multiple `` tags. Sveltia CMS will merge them in the order they appear in the HTML. ```html ``` ::: tip 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 [`deepmerge`](https://www.npmjs.com/package/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](https://json-schema.org/) 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](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) and adding the following comment to the top of `config.yml`: ```yaml # yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json ``` For TOML files, install the [Even Better TOML extension](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) and add the following comment to the top of `config.toml`: ```toml #:schema https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json ``` JSON 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: ```json "$schema": "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json", ``` ::: details 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](https://code.visualstudio.com/docs/configure/settings#_settings-json-file) at `.vscode/settings.json`, within the outer curly braces. For YAML files: ```jsonc "yaml.schemas": { "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json": ["/public/admin/config.yml"] } ``` For JSON files: ```jsonc "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. ::: #### 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.json ``` [WebStorm](https://www.jetbrains.com/help/webstorm/yaml.html#json_schema) 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](/en/docs/api), including the configuration object when [manually initializing](/en/docs/api/initialization) 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, so 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.score` field: The `min` option must be a number. Two sets of checks run. The first validates the whole configuration against the same [JSON schema](#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](/en/docs/api/field-types#field-schema) registered with its own schema joins these checks, so the options it accepts are validated alongside the built-in ones. The second covers the rules a schema can’t express — mostly mistakes that wouldn’t fail at all otherwise, but would quietly give you an empty collection, a random slug or a validation rule that never runs: * Backend: a missing or misspelled backend name, a `repo` that isn’t in the `owner/repo` format, a missing OAuth client ID, an empty `auth_methods` list, or Open Authoring without Editorial Workflow * Site-wide options: a `site_url` that isn’t an absolute URL, a `sanitize_replacement` slug option that itself contains a character slugs can’t have, an empty `i18n.locales` list, a `default_locale` or `initial_locales` entry that isn’t one of the `locales`, or a collection or file `i18n` option with no site-level i18n to build on * Internationalization: an `i18n` option that leaves nothing to translate — a site-level configuration that no collection or singleton enables with its own `i18n` option, an entry collection or collection file with i18n enabled but no field with `i18n: true` (or `translate`) or `i18n: duplicate`, or a file collection with i18n enabled but none of its files * Collections: duplicate or invalid collection, file, field and variable type names, a collection with none of `folder`, `files` or `divider` or more than one of them, a collection without fields, a configuration where every collection is hidden, and a mismatch between `format` and `extension` * Entry naming: an `identifier_field` that names no field, a collection with neither a `title` field nor an `identifier_field` or `slug` option, a `slug` template containing slashes, and `slug`, `path`, `summary`, `thumbnail` and `preview_path` options that refer to fields that don’t exist * Entry lists: a `filter` on an undefined field, with neither a `value` nor a `pattern`, or with a pattern that isn’t a valid regular expression; `sortable_fields`, `view_groups` and `view_filters` that refer to undefined fields; a `view_groups` or `view_filters` `default` that names no group or filter; a `reorder` group that isn’t defined * Fields: mutually exclusive options such as `field`, `fields` and `types`, an explicitly empty `fields` or `types` list, a validation `pattern` that isn’t a valid regular expression, a `min` above the `max` or a `minlength` above the `maxlength`, a Number `step` of zero or less, Select fields with no options or duplicate option values, and conflicting DateTime timezone options * Default values: a `default` whose shape doesn’t match the field’s other options — a Select `default` that isn’t among the `options`; a Select, Relation, File or Image `default` that is an array without `multiple` or a single value with it; a Number `default` that isn’t a number of the `value_type`; a Code `default` object with `output_code_only` or with a property that isn’t one of the `keys`; a List or Object `default` with 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 * References between fields: a Relation field whose `collection` or `file` doesn’t exist, or whose `value_field`, `display_fields`, `search_fields` or `filters` name fields the referenced collection doesn’t have; a Compute `value` template that names an undefined field; a List or Object `thumbnail` that names an undefined subfield, or one that isn’t an Image or File field * Options that Sveltia CMS doesn’t support, including deprecated camel case options such as `valueField` An option name the schema doesn’t define is a warning rather than an error, so that 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.Tutorial` option 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, which is why the console is worth a look whenever an option seems to do nothing. A YAML flow mapping quietly turns a comma-separated list into extra keys: ```yaml # `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] } ``` ::: tip Editor validation is still worth setting up [JSON schema validation in your editor](#json-schema) reports an unknown option as you type, before the CMS ever loads the file. :::