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:
- Entry Collection: the
summary,slug,pathandpreview_pathoptions - Compute Field: the
valueoption - Hidden Field: the
defaultoption - List Field: the
summaryoption - Object Field: the
summaryoption - Editor Components: the
summaryoption
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:
summary: '{{title | upper}}'summary = "{{title | upper}}"{
"summary": "{{title | upper}}"
}{
summary: "{{title | upper}}",
}lower
Transform the string to lowercase.
{{value | lower}}Configuration example:
summary: '{{title | lower}}'summary = "{{title | lower}}"{
"summary": "{{title | lower}}"
}{
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:
summary: '{{title | slugify}}'summary = "{{title | slugify}}"{
"summary": "{{title | slugify}}"
}{
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-testplainify
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:
value: "{{fields.body | plainify | truncate(160, '...')}}"value = "{{fields.body | plainify | truncate(160, '...')}}"{
"value": "{{fields.body | plainify | truncate(160, '...')}}"
}{
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 guestPut 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
plainifyon fields that contain them. A plain string can lose text, e.g.Vec<T>becomesVec, and1. IntroductionbecomesIntroduction. - 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
plainifyfunction, 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.
<img>becomes<img>, so escape it in your site templates. - A List or Object field’s
summaryalready shows a RichText field as plain text, soplainifyisn’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:
summary: '{{content | truncate(100)}}'summary = "{{content | truncate(100)}}"{
"summary": "{{content | truncate(100)}}"
}{
summary: "{{content | truncate(100)}}",
}summary: "{{content | truncate(100, '...')}}"summary = "{{content | truncate(100, '...')}}"{
"summary": "{{content | truncate(100, '...')}}"
}{
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:
summary: "{{description | default('No description available.')}}"summary = "{{description | default('No description available.')}}"{
"summary": "{{description | default('No description available.')}}"
}{
summary: "{{description | default('No description available.')}}",
}It’s possible to fall back to another field’s value using a nested template:
preview_path: "/{{fields.slug | default('{{fields.title}}')}}/"preview_path = "/{{fields.slug | default('{{fields.title}}')}}/"{
"preview_path": "/{{fields.slug | default('{{fields.title}}')}}/"
}{
preview_path: "/{{fields.slug | default('{{fields.title}}')}}/",
}A nested template can also combine several field values with other text:
summary: "{{fields.subtitle | default('{{fields.title}} by {{fields.author}}')}}"summary = "{{fields.subtitle | default('{{fields.title}} by {{fields.author}}')}}"{
"summary": "{{fields.subtitle | default('{{fields.title}} by {{fields.author}}')}}"
}{
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:
summary: "{{is_private | ternary('Private', 'Public')}}: {{title}}"summary = "{{is_private | ternary('Private', 'Public')}}: {{title}}"{
"summary": "{{is_private | ternary('Private', 'Public')}}: {{title}}"
}{
summary: "{{is_private | ternary('Private', 'Public')}}: {{title}}",
}summary: "{{title}} – {{featured | ternary('Featured', 'Regular')}} Event"summary = "{{title}} – {{featured | ternary('Featured', 'Regular')}} Event"{
"summary": "{{title}} – {{featured | ternary('Featured', 'Regular')}} Event"
}{
summary: "{{title}} – {{featured | ternary('Featured', 'Regular')}} Event",
}summary: "{{title}} {{published | ternary('', '(DRAFT)')}}"summary = "{{title}} {{published | ternary('', '(DRAFT)')}}"{
"summary": "{{title}} {{published | ternary('', '(DRAFT)')}}"
}{
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:
summary: "{{fields.subtitle | ternary('{{fields.title}}: {{fields.subtitle}}', '{{fields.title}}')}}"summary = "{{fields.subtitle | ternary('{{fields.title}}: {{fields.subtitle}}', '{{fields.title}}')}}"{
"summary": "{{fields.subtitle | ternary('{{fields.title}}: {{fields.subtitle}}', '{{fields.title}}')}}"
}{
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:
summary: "{{publish_date | date('YYYY-MM-DD')}}"summary = "{{publish_date | date('YYYY-MM-DD')}}"{
"summary": "{{publish_date | date('YYYY-MM-DD')}}"
}{
summary: "{{publish_date | date('YYYY-MM-DD')}}",
}summary: "{{publish_date | date('YYYY-MM-DD', 'utc')}}"summary = "{{publish_date | date('YYYY-MM-DD', 'utc')}}"{
"summary": "{{publish_date | date('YYYY-MM-DD', 'utc')}}"
}{
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:
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[[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"{
"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"
}
]
}
]
}{
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:
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 informationtitle = "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"{
"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:
summary: "{{title | upper | truncate(10, '...')}}"summary = "{{title | upper | truncate(10, '...')}}"{
"summary": "{{title | upper | truncate(10, '...')}}"
}{
summary: "{{title | upper | truncate(10, '...')}}",
}