Skip to content

String Transformations ​

String transformations allow manipulating and formatting string values in your content entries. These transformations can be applied in various contexts, such as generating summaries or formatting dates.

Note for Netlify/Decap CMS users

In Netlify/Decap CMS, this feature is known as summary string transformations. We simply refer to them as string transformations because, in Sveltia CMS, they can be used in multiple contexts beyond just entry summaries.

Available Contexts ​

String transformations can be applied in the following contexts:

Future Plans

More contexts may be added in future releases.

Syntax ​

String transformations are applied using the following syntax:

{{value | transformation_name}}

or with arguments:

{{value | transformation_name(arguments)}}

Where:

  • value: The original string value to be transformed. This is typically a field name enclosed in double curly braces (e.g. {{title}}).
  • transformation_name: The name of the transformation to apply (e.g. upper, lower, truncate).
  • arguments: Optional arguments required by certain transformations, enclosed in parentheses.

Multiple transformations can be chained together by separating them with a pipe (|). The output of one transformation serves as the input for the next. For example:

{{value | transformation1 | transformation2(arguments)}}

Notes on Syntax Rules ​

There are some syntax rules to keep in mind when using string transformations:

  • String arguments must be enclosed in single quotes.
  • Numeric arguments should not be quoted.
  • No spaces are allowed between the transformation name and the opening parenthesis.

Spaces inside the curly braces and around the pipe character (|) are optional, so {{ title | upper }} and {{title|upper}} are the same as {{title | upper}}. This applies to every template tag in the configuration, not only the ones with transformations, e.g. {{ slug }} in the path option or {{ locale }} in the folder option.

Escaping Template Tags ​

To output a template tag as is rather than have Sveltia CMS fill it in, put a backslash (\) right before the opening curly braces. The backslash is removed, and the rest of the tag is kept verbatim. This is useful when a value contains a template for another tool that uses the same double curly brace syntax, such as a static site generator like Eleventy or Hugo. For example, portfolio/\{{ title | slugify }}/index.html becomes portfolio/{{ title | slugify }}/index.html.

In a string format where the backslash is itself an escape character, write two backslashes (\\{{) so that one remains in the value. This applies to double-quoted strings in YAML and TOML, JSON and JavaScript. A single-quoted or unquoted YAML string takes a single backslash.

Escaping is supported in all the available contexts except the slug and path options of an entry collection.

Available Transformations ​

upper ​

Transform the string to uppercase.

{{value | upper}}

Configuration example:

yaml
summary: '{{title | upper}}'
toml
summary = "{{title | upper}}"
json
{
  "summary": "{{title | upper}}"
}
js
{
  summary: "{{title | upper}}",
}

lower ​

Transform the string to lowercase.

{{value | lower}}

Configuration example:

yaml
summary: '{{title | lower}}'
toml
summary = "{{title | lower}}"
json
{
  "summary": "{{title | lower}}"
}
js
{
  summary: "{{title | lower}}",
}

slugify ​

Convert the string to a URL-friendly slug.

{{value | slugify}}

The transformation converts the string based on the global slug options.

Configuration example:

yaml
summary: '{{title | slugify}}'
toml
summary = "{{title | slugify}}"
json
{
  "summary": "{{title | slugify}}"
}
js
{
  summary: "{{title | slugify}}",
}

For example, if the title field has the value Hello, World! This is a Test, the result will be:

hello-world-this-is-a-test

plainify ​

Convert a Markdown or HTML string to plain text by removing the Markdown syntax and HTML tags. Line breaks are collapsed into spaces, and character references like & are decoded.

{{value | plainify}}

This is useful for generating a description or an excerpt from a RichText field with a Compute field.

Configuration example:

yaml
value: "{{fields.body | plainify | truncate(160, '...')}}"
toml
value = "{{fields.body | plainify | truncate(160, '...')}}"
json
{
  "value": "{{fields.body | plainify | truncate(160, '...')}}"
}
js
{
  value: "{{fields.body | plainify | truncate(160, '...')}}",
}

For example, if the body field has the value Let’s **welcome** our [guest](https://example.com), the result will be:

Let’s welcome our guest

Put plainify before truncate so the limit applies to the visible text and the Markdown syntax isn’t cut in the middle.

Notes

  • The value is always parsed as Markdown and HTML, so only use plainify on fields that contain them. A plain string can lose text, e.g. Vec<T> becomes Vec, and 1. Introduction becomes Introduction.
  • Images are removed along with their alternative text. Syntax that isn’t Markdown or HTML, like Hugo shortcodes, is left as is.
  • Unlike Hugo’s plainify function, which only removes HTML tags, this transformation also removes the Markdown syntax.
  • The result is plain text, not sanitized HTML. It can contain markup after decoding, e.g. &lt;img&gt; becomes <img>, so escape it in your site templates.
  • A List or Object field’s summary already shows a RichText field as plain text, so plainify isn’t needed there.

truncate ​

Truncate the string to a specified length, adding a suffix if anything is cut off.

{{value | truncate(<length>)}}
{{value | truncate(<length>, '<suffix>')}}

The length argument specifies the maximum number of characters to keep. If the string exceeds this length, it’s truncated, and the suffix is appended.

The optional suffix argument defaults to an ellipsis (…). Specify another string to use instead, e.g. '...', or an empty string ('') to cut the string without adding anything.

Configuration examples:

yaml
summary: '{{content | truncate(100)}}'
toml
summary = "{{content | truncate(100)}}"
json
{
  "summary": "{{content | truncate(100)}}"
}
js
{
  summary: "{{content | truncate(100)}}",
}
yaml
summary: "{{content | truncate(100, '...')}}"
toml
summary = "{{content | truncate(100, '...')}}"
json
{
  "summary": "{{content | truncate(100, '...')}}"
}
js
{
  summary: "{{content | truncate(100, '...')}}",
}

default ​

Provide a default value if the original value is null or empty.

{{value | default('<default_value>')}}

The default_value is returned if the original value is null or an empty string; otherwise, the original value is returned. The default_value can also be an empty string, e.g. default('').

Configuration example:

yaml
summary: "{{description | default('No description available.')}}"
toml
summary = "{{description | default('No description available.')}}"
json
{
  "summary": "{{description | default('No description available.')}}"
}
js
{
  summary: "{{description | default('No description available.')}}",
}

It’s possible to fall back to another field’s value using a nested template:

yaml
preview_path: "/{{fields.slug | default('{{fields.title}}')}}/"
toml
preview_path = "/{{fields.slug | default('{{fields.title}}')}}/"
json
{
  "preview_path": "/{{fields.slug | default('{{fields.title}}')}}/"
}
js
{
  preview_path: "/{{fields.slug | default('{{fields.title}}')}}/",
}

A nested template can also combine several field values with other text:

yaml
summary: "{{fields.subtitle | default('{{fields.title}} by {{fields.author}}')}}"
toml
summary = "{{fields.subtitle | default('{{fields.title}} by {{fields.author}}')}}"
json
{
  "summary": "{{fields.subtitle | default('{{fields.title}} by {{fields.author}}')}}"
}
js
{
  summary: "{{fields.subtitle | default('{{fields.title}} by {{fields.author}}')}}",
}

ternary ​

Choose between two values based on the truthiness of the original value.

{{value | ternary('<true_value>', '<false_value>')}}

The true_value is returned if the original value is truthy; otherwise, the false_value is returned.

Configuration examples:

yaml
summary: "{{is_private | ternary('Private', 'Public')}}: {{title}}"
toml
summary = "{{is_private | ternary('Private', 'Public')}}: {{title}}"
json
{
  "summary": "{{is_private | ternary('Private', 'Public')}}: {{title}}"
}
js
{
  summary: "{{is_private | ternary('Private', 'Public')}}: {{title}}",
}
yaml
summary: "{{title}} – {{featured | ternary('Featured', 'Regular')}} Event"
toml
summary = "{{title}} – {{featured | ternary('Featured', 'Regular')}} Event"
json
{
  "summary": "{{title}} – {{featured | ternary('Featured', 'Regular')}} Event"
}
js
{
  summary: "{{title}} – {{featured | ternary('Featured', 'Regular')}} Event",
}
yaml
summary: "{{title}} {{published | ternary('', '(DRAFT)')}}"
toml
summary = "{{title}} {{published | ternary('', '(DRAFT)')}}"
json
{
  "summary": "{{title}} {{published | ternary('', '(DRAFT)')}}"
}
js
{
  summary: "{{title}} {{published | ternary('', '(DRAFT)')}}",
}

As with the default transformation, the true_value and false_value can contain nested templates to use other field values. For example, show the subtitle after the title only when it’s available:

yaml
summary: "{{fields.subtitle | ternary('{{fields.title}}: {{fields.subtitle}}', '{{fields.title}}')}}"
toml
summary = "{{fields.subtitle | ternary('{{fields.title}}: {{fields.subtitle}}', '{{fields.title}}')}}"
json
{
  "summary": "{{fields.subtitle | ternary('{{fields.title}}: {{fields.subtitle}}', '{{fields.title}}')}}"
}
js
{
  summary: "{{fields.subtitle | ternary('{{fields.title}}: {{fields.subtitle}}', '{{fields.title}}')}}",
}

date ​

Format a date string, with an optional timezone.

{{value | date('<format>')}}
{{value | date('<format>', '<timezone>')}}

The format argument specifies the desired date format using Day.js formatting tokens.

The optional timezone argument allows you to specify the timezone for formatting. It only supports utc for Coordinated Universal Time. If no timezone is provided, the local timezone will be used.

If the value comes from a DateTime field with a custom format option, such as DD/MM/YYYY or X (Unix timestamp), it’s parsed in that format. If an invalid date is provided, an empty string will be returned.

Configuration examples:

yaml
summary: "{{publish_date | date('YYYY-MM-DD')}}"
toml
summary = "{{publish_date | date('YYYY-MM-DD')}}"
json
{
  "summary": "{{publish_date | date('YYYY-MM-DD')}}"
}
js
{
  summary: "{{publish_date | date('YYYY-MM-DD')}}",
}
yaml
summary: "{{publish_date | date('YYYY-MM-DD', 'utc')}}"
toml
summary = "{{publish_date | date('YYYY-MM-DD', 'utc')}}"
json
{
  "summary": "{{publish_date | date('YYYY-MM-DD', 'utc')}}"
}
js
{
  summary: "{{publish_date | date('YYYY-MM-DD', 'utc')}}",
}

Breaking change from Netlify/Decap CMS

Sveltia CMS (and Decap CMS 3.1.1) replaced the Moment.js library with Day.js for date formatting and parsing. Since Day.js tokens are not 100% compatible with Moment.js tokens, this could be a breaking change in certain cases. Check your date/time format if you’re migrating from Netlify CMS or earlier versions of Decap CMS.

Custom Transformations ​

In addition to the built-in transformations, you can register your own with the CMS.registerStringTransformation() method, and use them like {{title | reverse}} or {{title | wrap('[', ']')}}. See Custom String Transformations for details.

Examples ​

Summary with Multiple Transformations ​

The below example demonstrates how to use multiple string transformations in the summary option of a collection:

yaml
collections:
  - name: blog
    label: Blog
    summary: "{{title | upper}} — {{publish_date | date('YYYY-MM-DD')}} — {{body | truncate(20, '...')}}"
    fields:
      - name: title
        label: Title
        widget: string
      - name: publish_date
        label: Publish Date
        widget: datetime
      - name: body
        label: Body
        widget: richtext
toml
[[collections]]
name = "blog"
label = "Blog"
summary = "{{title | upper}} — {{publish_date | date('YYYY-MM-DD')}} — {{body | truncate(20, '...')}}"

[[collections.fields]]
name = "title"
label = "Title"
widget = "string"

[[collections.fields]]
name = "publish_date"
label = "Publish Date"
widget = "datetime"

[[collections.fields]]
name = "body"
label = "Body"
widget = "richtext"
json
{
  "collections": [
    {
      "name": "blog",
      "label": "Blog",
      "summary": "{{title | upper}} — {{publish_date | date('YYYY-MM-DD')}} — {{body | truncate(20, '...')}}",
      "fields": [
        {
          "name": "title",
          "label": "Title",
          "widget": "string"
        },
        {
          "name": "publish_date",
          "label": "Publish Date",
          "widget": "datetime"
        },
        {
          "name": "body",
          "label": "Body",
          "widget": "richtext"
        }
      ]
    }
  ]
}
js
{
  collections: [
    {
      name: "blog",
      label: "Blog",
      summary: "{{title | upper}} — {{publish_date | date('YYYY-MM-DD')}} — {{body | truncate(20, '...')}}",
      fields: [
        {
          name: "title",
          label: "Title",
          widget: "string",
        },
        {
          name: "publish_date",
          label: "Publish Date",
          widget: "datetime",
        },
        {
          name: "body",
          label: "Body",
          widget: "richtext",
        },
      ],
    },
  ],
}

It will transform the title to uppercase, format the publish_date to YYYY-MM-DD and truncate the body to 20 characters with an ellipsis. For example, if an entry has the following values:

yaml
title: My First Blog Post
publish_date: 2024-06-15T10:30:00Z
body: This is the content of my first blog post. It has a lot of interesting information
toml
title = "My First Blog Post"
publish_date = 2024-06-15T10:30:00Z
body = "This is the content of my first blog post. It has a lot of interesting information"
json
{
  "title": "My First Blog Post",
  "publish_date": "2024-06-15T10:30:00Z",
  "body": "This is the content of my first blog post. It has a lot of interesting information"
}

The resulting summary will be:

MY FIRST BLOG POST — 2024-06-15 — This is the content...

Chaining Transformations ​

You can chain multiple transformations together by separating them with a pipe (|). For example, to convert a title to uppercase and then truncate it to 10 characters, you can use:

yaml
summary: "{{title | upper | truncate(10, '...')}}"
toml
summary = "{{title | upper | truncate(10, '...')}}"
json
{
  "summary": "{{title | upper | truncate(10, '...')}}"
}
js
{
  summary: "{{title | upper | truncate(10, '...')}}",
}