Skip to content

Data Output ​

Content in Sveltia CMS is stored in static files, which can be in various formats such as Markdown, YAML, TOML or JSON. The format used for storing content can be configured on a per-collection basis.

In most cases, you don’t need to worry about the details of data output. Sveltia CMS and the tools that consume your content, like your frameworks, static site generators (SSGs) or parser libraries, handle it seamlessly. However, understanding how data is output can help you avoid unexpected issues, especially when using strict type validations or manually editing data files.

File Formats ​

Standard Formats ​

Sveltia CMS supports the following data output formats for content files out of the box:

  • Markdown with YAML, TOML or JSON front matter
  • YAML
  • TOML
  • JSON
  • Raw text files, such as plain text, JSON, XML or CSV files

To customize the format for each collection, see the Entry Collection File Formats and File Collection documentation.

Custom Formats ​

Sveltia CMS allows you to define custom data output formats using the API. You can create your own format handlers to meet specific requirements for your project. For more information on how to create custom formats, please refer to the Custom File Formats API reference.

Data Output Conventions ​

Here are some key aspects of data output in Sveltia CMS.

General Conventions ​

  • Field Order: Fields are saved as key-value pairs in the order they are defined in the configuration, which keeps Git diffs clean and consistent. Some exceptions apply.
  • Line Breaks: Line breaks are LF (\n) across all formats. A newline is added at the end of the file to prevent unnecessary changes.
  • Time Format: A standard time is formatted as HH:mm:ss instead of HH:mm for better framework compatibility, including Hugo.

Whitespace ​

Unnecessary whitespace in string values is automatically removed when an entry is saved. No configuration option is required for this behavior.

  • Code field values are saved as they are, because any whitespace, such as the indentation of the first line or a final newline, can be significant in code.
  • Text, Markdown and rich text field values keep their leading whitespace, such as the indentation of a code block on the first line. Only trailing whitespace is removed.
  • Leading and trailing whitespace is removed from any other string value.

Empty Values ​

Sveltia CMS saves proper values for all fields, such as an empty string, an empty array or null, instead of omitting them. This differs from Netlify/Decap CMS, which often omits optional and empty fields.

  • required: false makes data input optional, but doesn’t make data output optional.
  • To omit empty optional fields from data output, use omit_empty_optional_fields: true in the output options. This is useful if you have data type validations that expect undefined.
  • That option never omits a List item. An item whose subfields are all empty is kept as an empty object ({}), so the other items keep their positions.

Existing Data ​

Values the CMS reads from an existing file are written back unchanged unless they are edited:

  • Object keys containing a dot, such as example.com in a KeyValue field or in data not covered by the configuration, are kept as they are rather than being split into nested objects.
  • Object keys that look like numbers, such as 2024, stay object keys rather than turning the object into a list.
  • Integers too large for JavaScript to represent exactly (beyond 253, such as a 19-digit ID) are written back exactly as they appear in the file.
  • Floats that are whole numbers, such as 10.0 or 1e3, stay floats rather than becoming integers like 10. This way, tools that tell the two apart, such as Hugo’s eq, see the same type. This applies to YAML, JSON and TOML.
  • Native TOML dates and times, such as 2024-01-01T10:00:00Z or 12:30:00, are written back as they appear in the file. This applies to any field, not just DateTime fields, and to data not covered by the configuration.

Formatting details, such as the quote style of a YAML string, aren’t kept. Neither are comments, except those at the top of a YAML or TOML file. See YAML and TOML for details.

Format-Specific Conventions ​

YAML ​

  • Indentation: 2 spaces by default. Sequences are indented under their key. Both are configurable in the output options.

  • Line Width: Long strings aren’t wrapped, as string folding (maximum line width) is disabled for better framework compatibility.

  • Quoting: Strings can be unquoted, single-quoted or double-quoted (configurable). Even when unquoted, a string that a YAML 1.1 parser would read as a boolean or a number is always quoted. This way, tools still using YAML 1.1, such as Jekyll and older Hugo releases, read it as a string. This covers:

    • values like yes, no, on, off, y and n in any of their usual capitalizations
    • numbers with underscores or commas, like 1_000
    • sexagesimal numbers like 1:20, which a YAML 1.1 parser reads as 80

    Dates aren’t quoted, so they are still read as dates.

  • Multi-Line Strings: A string with line breaks is written as a literal block scalar (|) by default (configurable). See Multi-Line Strings in YAML for details.

  • Comments: When an entry is saved, comments at the top of an existing file or front matter block are kept, as long as a blank line separates them from the first key. Other comments aren’t kept, because the CMS writes the whole file from the entry data. To add a comment before a field, use the comment field option.

    yaml
    # Kept
    # Also kept
    
    # Not kept: directly above the first key
    title: Hello

TOML ​

  • Comments: As with YAML, when an entry is saved, comments at the top of an existing file or front matter block are kept, as long as a blank line separates them from the first key or table. Other comments aren’t kept, and the comment field option isn’t supported.
  • Empty List Items: TOML has no null value, so an empty item in a list, such as a cleared optional Number field in a simple list, is left out of a TOML file or TOML front matter. YAML and JSON keep it as null.
  • DateTime Values: DateTime field values in ISO 8601 format are stored in native date/time format instead of quoted strings. This applies to TOML files and TOML front matter, including entries with TOML front matter in a collection using the frontmatter format. It doesn’t apply if the field has a custom format option. A value that isn’t a valid date or time, such as TBD, is kept as a string.

JSON ​

  • Indentation: 2 spaces by default. The indent style (spaces or tabs) and size are configurable in the output options.

Markdown Syntax ​

Due to the underlying Lexical framework used in Sveltia CMS, the following Markdown conventions are applied to the output of the rich text editor.

Markdown Style ​

  • Indentation: 4 spaces for nested lists and code blocks instead of 2 spaces.
  • Unordered List Markers: A list keeps the markers it was written or typed with, like asterisks (*) or plus signs (+). Hyphens (-) are used for any other unordered list or task list, like one created from the toolbar or pasted from a web page.
  • Task List Items: A checked task list item is written with a lowercase x, like - [x] item, even if it was written with an uppercase X.
  • Bold Text: Double asterisks (**) are used for bold text instead of double underscores (__).
  • Italic Text: Underscores (_) are used for italics instead of asterisks (*), except within a word, like a*b*c, where underscores don’t work.
  • Headings: Hash signs (#) are used for headings. Headings underlined with === or --- are converted to this style.
  • Code Blocks: Backticks (`) are used to fence code blocks. Code blocks fenced with tildes (~~~) are converted to this style, and a code block without a language is given the plain language.
  • Horizontal Rules: Three asterisks (***) are used for horizontal rules instead of three hyphens (---).
  • Line Breaks: Soft line breaks (single line breaks) are used instead of hard line breaks (two or more spaces, escaped line breaks \ or HTML <br> tags). In your framework, you may need to enable the appropriate option to render soft line breaks as hard line breaks.
  • Tight Lists: Blank lines between list items are removed, so a loose list becomes a tight one.
  • Escapes: Backslash escapes that aren’t needed are removed, like the one in snake\_case. Escaped square brackets (\[, \]) and angle brackets (\<, \>) are written without the backslash.
  • Character References: Numeric character references, like &#169;, are written as the characters they stand for, like ©. Named ones, like &copy;, are kept.

Unsupported Syntax ​

The rich text editor doesn’t support some Markdown syntax. You can still edit content that uses it, but it’s changed as follows once the content is saved in the rich text mode. To keep such content as is, edit it in the raw mode instead:

  • Table Column Alignment: The alignment in the delimiter row of a table, like :-- or :-:, is dropped, so all columns use the default alignment.
  • Code Blocks in List Items: A fenced code block within a list item is moved out of the list.
  • Single-Tilde Strikethrough: Strikethrough with single tildes, like ~text~, is turned into text, with the tildes escaped. Use double tildes, like ~~text~~, instead.
  • Adjacent Lists: Consecutive lists that only differ in their markers, like a - list followed by a * list, are merged into one list.
  • Formatting Across Links: Bold, italic or strikethrough text that spans a link and other text, like **[text](url) more**, is split at the link, like **[text](url)** **more**. Formatting around a whole link, like **[text](url)**, is kept as it is.

Syntax Kept as Text ​

Some other syntax the editor can’t edit as such is shown as text and saved as written, so it isn’t changed:

  • Blocks Within Block Quotes and List Items: A block quote within another one, like > > text, a list, heading or code block within a block quote, and a block quote within a list item.
  • Ordered Lists with Parentheses: An ordered list using a closing parenthesis, like 1). Use a period, like 1., to edit it as a list.

Controlling Data Output ​

You can control data output, including JSON and YAML formatting, with the output option at the root level of the configuration file. Here are the default options:

yaml
output:
  omit_empty_optional_fields: false
  encode_file_path: false # true to URL-encode file paths for File/Image fields
  json:
    indent_style: space # or tab
    indent_size: 2
  yaml:
    quote: none # or single or double
    indent_size: 2
    indent_sequences: true # false for compact style
    block_quote: true # or literal, folded or false
toml
[output]
omit_empty_optional_fields = false
encode_file_path = false # true to URL-encode file paths for File/Image fields
[output.json]
indent_style = "space" # or "tab"
indent_size = 2
[output.yaml]
quote = "none" # or "single" or "double"
indent_size = 2
indent_sequences = true # false for compact style
block_quote = true # or "literal", "folded" or false
json
{
  "output": {
    "omit_empty_optional_fields": false,
    "encode_file_path": false,
    "json": {
      "indent_style": "space",
      "indent_size": 2
    },
    "yaml": {
      "quote": "none",
      "indent_size": 2,
      "indent_sequences": true,
      "block_quote": true
    }
  }
}
js
{
  output: {
    omit_empty_optional_fields: false,
    encode_file_path: false,
    json: {
      indent_style: 'space',
      indent_size: 2,
    },
    yaml: {
      quote: 'none',
      indent_size: 2,
      indent_sequences: true,
      block_quote: true,
    },
  },
}

For JSON, indent_size is the number of spaces or tabs per indent level; it defaults to 2 with indent_style: space and 1 with indent_style: tab. For YAML, quote: none leaves string values unquoted unless quotes are required, while single and double wrap them in single or double quotes.

Multi-Line Strings in YAML ​

The block_quote option for YAML controls how a string with line breaks is written. It only applies when quote is none. With single or double, multi-line strings are quoted like any other string.

  • true or literal (default): a literal block scalar (|), which keeps line breaks as they are.
  • folded: a folded block scalar (>). A single line break in a folded scalar is read as a space, so each line break in the value is written as a blank line. Long lines still aren’t wrapped, as string folding is disabled.
  • false: a quoted string, with a blank line for each line break. It’s single-quoted, unless the string contains a single quote, in which case it’s double-quoted.

For example, a value with two paragraphs is written as follows:

yaml
about: |-
  First paragraph.

  Second paragraph.
yaml
about: >-
  First paragraph.


  Second paragraph.
yaml
about: 'First paragraph.


  Second paragraph.'

The block chomping indicator after | or > can’t be configured, because it depends on the value: - if the value has no trailing line break, no indicator if it has one, and + if it has more.

Understanding Exceptions ​

Content is generally saved as key-value pairs in a file, where the key is the field name and the value is the field value. However, there are some exceptions you should be aware of.

The body Field ​

If the format is front matter, the body field is saved outside of the front matter block:

markdown
---
title: My Post
date: 2025-01-01
---

This is the body of my post.

instead of

yaml
---
title: My Post
date: 2025-01-01
body: This is the body of my post.
---

If there is only the body field, the front matter block is omitted altogether:

markdown
This is the body of my post.

This behavior can be configured using the body_field option for collections and collection files.

When i18n is enabled with the single_file structure, this behavior doesn’t apply at all. In this case, the body field is saved as part of key-value pairs under each locale in the front matter block:

yaml
---
en:
  title: My Post
  date: 2025-01-01
  body: This is the body of my post.
fr:
  title: Mon article
  date: 2025-01-01
  body: C’est le corps de mon article.
---

List Field ​

There are two exceptional cases for the List field:

field vs. fields Option ​

When the fields (plural) option is used, each item is saved as an object with key-value pairs. For example, the following configuration:

yaml
- name: images
  label: Images
  widget: list
  fields:
    - { name: image, label: Image, widget: image }
toml
[[fields]]
name = "images"
label = "Images"
widget = "list"
[[fields.fields]]
name = "image"
label = "Image"
widget = "image"
json
{
  "fields": [
    {
      "name": "images",
      "label": "Images",
      "widget": "list",
      "fields": [
        { "name": "image", "label": "Image", "widget": "image" }
      ]
    }
  ]
}
js
{
  fields: [
    {
      name: "images",
      label: "Images",
      widget: "list",
      fields: [
        { name: "image", label: "Image", widget: "image" },
      ],
    },
  ],
}

will produce the output:

yaml
images:
  - image: https://example.com/image1.jpg
  - image: https://example.com/image2.jpg
toml
[[images]]
image = "https://example.com/image1.jpg"
[[images]]
image = "https://example.com/image2.jpg"
json
{
  "images": [
    { "image": "https://example.com/image1.jpg" },
    { "image": "https://example.com/image2.jpg" }
  ]
}

On the other hand, when the field (singular) option is used, the name property is omitted from the output.

yaml
- name: images
  label: Images
  widget: list
  field: { name: image, label: Image, widget: image }
toml
[[fields]]
name = "images"
label = "Images"
widget = "list"
[fields.field]
name = "image"
label = "Image"
widget = "image"
json
{
  "fields": [
    {
      "name": "images",
      "label": "Images",
      "widget": "list",
      "field": { "name": "image", "label": "Image", "widget": "image" }
    }
  ]
}
js
{
  fields: [
    {
      name: "images",
      label: "Images",
      widget: "list",
      field: { name: "image", label: "Image", widget: "image" },
    },
  ],
}

The output will be:

yaml
images:
  - https://example.com/image1.jpg
  - https://example.com/image2.jpg
toml
images = ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
json
{
  "images": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
}

root Option ​

When the root option is set to true, the List field is saved as a top-level list without a field name:

yaml
- name: John Doe
  id: 12345
- name: Jane Smith
  id: 67890
json
[
  { "name": "John Doe", "id": 12345 },
  { "name": "Jane Smith", "id": 67890 }
]

instead of

yaml
members:
  - name: John Doe
    id: 12345
  - name: Jane Smith
    id: 67890
json
{
  "members": [
    { "name": "John Doe", "id": 12345 },
    { "name": "Jane Smith", "id": 67890 }
  ]
}

This root option doesn’t work with the TOML format, as TOML doesn’t support top-level arrays.