Sveltia CMS

File Collections ​

A file collection contains pre-defined files, each representing a single piece of content. Editors can edit the content of these files but cannot add new files or delete existing ones. A listed file that doesn’t exist yet is created when it’s first saved. Typical use cases for file collections include site settings, homepage content or about pages.

Creating a File Collection ​

The example below defines a file collection for managing static pages:

yaml
collections:
  - name: pages
    label: Pages
    files:
      - name: about
        label: About Page
        file: content/pages/about.md
        fields:
          - { name: title, label: Title }
          - { name: body, label: Body, widget: richtext }
toml
[[collections]]
name = "pages"
label = "Pages"

[[collections.files]]
name = "about"
label = "About Page"
file = "content/pages/about.md"

[[collections.files.fields]]
name = "title"
label = "Title"

[[collections.files.fields]]
name = "body"
label = "Body"
widget = "richtext"
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/pages/about.md",
          "fields": [
            { "name": "title", "label": "Title" },
            { "name": "body", "label": "Body", "widget": "richtext" }
          ]
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/pages/about.md",
          fields: [
            { name: "title", label: "Title" },
            { name: "body", label: "Body", widget: "richtext" },
          ],
        },
      ],
    },
  ],
}

Each file in the collection is defined with a name, label, file path, and a set of fields. Editors can modify the content of these files through the Sveltia CMS interface.

Collection Options ​

A file collection supports the following options:

  • name: A unique identifier for the collection. Required.
  • label: A human-readable name for the collection. Optional.
  • label_singular: A human-readable singular name for the collection. Optional. Used in the editor title when a file that doesn’t exist yet is being created.
  • description: A brief description of the collection, displayed in the UI. Optional. Basic Markdown formatting is supported.
  • icon: A Material Symbols icon name to represent the collection in the CMS UI. Optional.
  • files: An array of file definitions within the collection. Required.
  • hide: Whether to hide the collection from the UI. Optional. See Hiding the Collection.
  • format, frontmatter_delimiter, body_field: The default file format options for the files in the collection. Optional. Each file can override them. See below for details.
  • media_folder, public_folder: Media folder options for the collection. Optional. See Collection-Level Configuration.
  • i18n: I18n options for the collection. Optional. Each file also needs its own i18n option to be localized. See Collection-Level Configuration.
  • editor: Content Editor options, such as preview: false to disable the preview pane. Optional. See Disabling Previews.
  • publish_mode: The publish mode for the collection, overriding the top-level option. Optional. See Enabling the Workflow per Collection.
  • publish: Set to false to hide the publishing controls in Editorial Workflow. Optional. See Restricting Publishing and Deletion.
  • readonly: Set to true to make every file in the collection read-only. Optional. See Making Content Read-Only.

Unlike entry collections, the collection-level preview_path and preview_path_date_field options don’t apply to file collections. Set them on each file instead.

File Options ​

A file definition within a file collection supports the following options:

  • name: A unique identifier for the file within the collection. Required.
  • label: A human-readable name for the file. Optional.
  • icon: A Material Symbols icon name to represent the file in the CMS UI. Optional.
  • file: The path to the file in the content repository. Required.
  • format: The file format (e.g., yaml, json, toml, yaml-frontmatter, etc.). Optional. See below for details.
  • frontmatter_delimiter: The front matter delimiter. Optional. See below for details.
  • body_field: The body field options for front matter formats. Optional. See below for details.
  • fields: An array of field definitions for the file content. Required.
  • media_folder, public_folder: Media folder options for the file, overriding the top-level and collection-level options. Optional. See File-Level Configuration.
  • i18n: I18n options for the file. Optional. See File-Level Configuration.
  • editor: Content Editor options for the file, overriding the collection-level options. Optional. See Disabling Previews.
  • readonly: Set to true to make the file read-only, while the other files in the collection stay editable. Optional. See Making Content Read-Only.
  • preview_path, preview_path_date_field: The file’s URL path on the live site. Optional. See below for details.

A listed file doesn’t have to exist in the repository. If it’s missing, the Content Editor opens with empty fields (or their default values), and the file is created when the editor saves it.

File Format and Extension ​

The file format and extension for each file in a file collection can be customized using the format property within each file definition. Sveltia CMS supports various file formats, including Markdown, YAML, JSON, and TOML.

By default, file format is determined based on the file extension. If it is a Markdown file (e.g., .md), it uses the frontmatter format, which detects YAML, TOML or JSON front matter automatically; a new file is saved with YAML front matter. For other extensions, it uses the corresponding format (e.g., .yaml uses yaml format). See Default Format and Extension for the full list.

To illustrate, here is a file collection with two files using different formats:

yaml
collections:
  - name: pages
    label: Pages
    files:
      - name: about
        label: About Page
        file: content/pages/about.json
        fields:
          - { name: title, label: Title }
          - { name: body, label: Body, widget: richtext }
      - name: contact
        label: Contact Page
        file: content/pages/contact.yaml
        fields:
          - { name: title, label: Title }
          - { name: body, label: Body, widget: richtext }
toml
[[collections]]
name = "pages"
label = "Pages"

[[collections.files]]
name = "about"
label = "About Page"
file = "content/pages/about.json"

[[collections.files.fields]]
name = "title"
label = "Title"

[[collections.files.fields]]
name = "body"
label = "Body"
widget = "richtext"

[[collections.files]]
name = "contact"
label = "Contact Page"
file = "content/pages/contact.yaml"

[[collections.files.fields]]
name = "title"
label = "Title"

[[collections.files.fields]]
name = "body"
label = "Body"
widget = "richtext"
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/pages/about.json",
          "fields": [
            { "name": "title", "label": "Title" },
            { "name": "body", "label": "Body", "widget": "richtext" }
          ]
        },
        {
          "name": "contact",
          "label": "Contact Page",
          "file": "content/pages/contact.yaml",
          "fields": [
            { "name": "title", "label": "Title" },
            { "name": "body", "label": "Body", "widget": "richtext" }
          ]
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/pages/about.json",
          fields: [
            { name: "title", label: "Title" },
            { name: "body", label: "Body", widget: "richtext" },
          ],
        },
        {
          name: "contact",
          label: "Contact Page",
          file: "content/pages/contact.yaml",
          fields: [
            { name: "title", label: "Title" },
            { name: "body", label: "Body", widget: "richtext" },
          ],
        },
      ],
    },
  ],
}

Format ​

To explicitly set the file format, you can add the format property to each file definition. This is useful if you want to use TOML or JSON formats for Markdown files. Here is an example:

yaml
collections:
  - name: pages
    label: Pages
    format: json-frontmatter
    files:
      - name: about
        label: About Page
        file: content/pages/about.md
toml
[[collections]]
name = "pages"
label = "Pages"
format = "json-frontmatter"

[[collections.files]]
name = "about"
label = "About Page"
file = "content/pages/about.md"
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "format": "json-frontmatter",
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/pages/about.md"
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      format: "json-frontmatter",
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/pages/about.md",
        },
      ],
    },
  ],
}

The format can be set at the collection level to apply to all files within that collection, or at the individual file level to override the collection setting for specific files.

Note that when specifying a format, ensure that the file extension matches the chosen format to avoid confusion. If there is an obvious mismatch between the file extension and the specified format, Sveltia CMS will raise a validation error.

Extension ​

Unlike entry collections, file collections do not support the extension option to define allowed file extensions, since each file is pre-defined with a specific path containing its extension.

Extension-less files are supported in file collections. When using extension-less files, it is recommended to explicitly set the format property to ensure the correct parsing of the file content. If format is not set, it defaults to yaml-frontmatter.

See Editing site deployment configuration files in our how-tos for an example of using extension-less files in a file collection.

Front Matter Delimiter ​

As with entry collections, the frontmatter_delimiter option can also be used to customize the front matter delimiter for Markdown files, either at the collection or file level. Here is an example of setting both format and frontmatter_delimiter at the file level:

yaml
collections:
  - name: pages
    label: Pages
    files:
      - name: about
        label: About Page
        file: content/pages/about.md
        format: toml-frontmatter
        frontmatter_delimiter: ~~~
toml
[[collections]]
name = "pages"
label = "Pages"

[[collections.files]]
name = "about"
label = "About Page"
file = "content/pages/about.md"
format = "toml-frontmatter"
frontmatter_delimiter = "~~~"
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/pages/about.md",
          "format": "toml-frontmatter",
          "frontmatter_delimiter": "~~~"
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/pages/about.md",
          format: "toml-frontmatter",
          frontmatter_delimiter: "~~~",
        },
      ],
    },
  ],
}

Body Field for Front Matter Formats ​

When using front matter formats (e.g., yaml-frontmatter, toml-frontmatter, json-frontmatter), you can configure the body field to specify where the main content of the file should be stored. By default, the body field is named body, but you can customize this by setting the body_field option at either the collection or file level.

See Body Field for Front Matter Formats in the entry collections documentation for more details.

Preview Path ​

A file has no preview link by default. To link it to its page on the live site, or on a deploy preview, set the preview_path option on the file. It works like the collection-level preview_path option of an entry collection, with the following differences:

  • {{slug}} is the file’s name option value.
  • {{dirname}} is the directory of the file path, relative to the repository’s root directory, since a file collection has no folder.
  • Field values, date/time tags, {{filename}}, {{extension}} and {{locale}} are filled in the same way, using the file’s own fields. The date/time tags use the file’s first DateTime field unless preview_path_date_field is set.
yaml
collections:
  - name: pages
    label: Pages
    files:
      - name: about
        label: About Page
        file: content/pages/about.md
        preview_path: /about/
        fields:
          - { name: title, label: Title }
          - { name: body, label: Body, widget: richtext }
toml
[[collections]]
name = "pages"
label = "Pages"

[[collections.files]]
name = "about"
label = "About Page"
file = "content/pages/about.md"
preview_path = "/about/"

[[collections.files.fields]]
name = "title"
label = "Title"

[[collections.files.fields]]
name = "body"
label = "Body"
widget = "richtext"
json
{
  "collections": [
    {
      "name": "pages",
      "label": "Pages",
      "files": [
        {
          "name": "about",
          "label": "About Page",
          "file": "content/pages/about.md",
          "preview_path": "/about/",
          "fields": [
            { "name": "title", "label": "Title" },
            { "name": "body", "label": "Body", "widget": "richtext" }
          ]
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "pages",
      label: "Pages",
      files: [
        {
          name: "about",
          label: "About Page",
          file: "content/pages/about.md",
          preview_path: "/about/",
          fields: [
            { name: "title", label: "Title" },
            { name: "body", label: "Body", widget: "richtext" },
          ],
        },
      ],
    },
  ],
}

Singletons ​

The singleton collection is a special type of file collection that allows you to manage a set of pre-defined files without the ability to create or delete them. Singletons are useful for managing site-wide settings or content that should only exist as a single instance. See Singletons for more details.

Copyright © 2026 Kohei Yoshino