RichText Field

The RichText field type provides a rich text editor that supports both Markdown and HTML content. It allows content editors to format text, add links, images, and other media, making it a versatile choice for creating rich content.

Note for Netlify/Decap CMS users

For backward compatibility with Netlify/Decap CMS, the Markdown field type remains available as an alias of the RichText field type. You can use either richtext or markdown as the widget value in your field configuration.

User Interface

Editor

A Lexical-based rich text editor, including headings, lists, links, images, code blocks, and more. It provides a user-friendly interface for writing and formatting content.

The built-in toolbar includes buttons for common formatting options, which can be customized using the buttons option. The editor also supports different modes, including a raw Markdown or HTML editing mode, which can be configured using the modes option. Additional editor components can be added to enhance the editing experience using the editor_components option.

Links are edited in a floating link editor. Placing the cursor in a link shows its URL along with buttons to edit or remove the link, and selecting text and clicking the Link button or pressing Ctrl+K/Command+K opens the editor to enter a URL for the text. Without a selection, the Link button opens a dialog to insert a link along with its text.

Local/remote images can be pasted or dropped into the editor to insert them. Note: pasting multiple images is not supported in Firefox.

Emoji autocomplete is enabled by default. Typing a colon followed by one or more characters, such as :smi, brings up a list of matching emojis, the same way it works on GitHub, Slack and other apps. Use the arrow keys to move through the list, the Enter or Tab key to insert the selected emoji, and the Escape key to dismiss the list. This can be turned off with the use_emoji_autocomplete option.

Paragraphs and Line Breaks

In the editor, pressing Enter inserts a new paragraph, while pressing Shift+Enter inserts a line break within the current paragraph.

Breaking change from Netlify/Decap CMS

Remark plugins are not supported because Sveltia CMS uses the Lexical framework instead of Slate. The CMS.registerRemarkPlugin API method is a noop in Sveltia CMS.

Preview

A read-only view of the rich text content, rendered as HTML.

Data Type

If the format option is set to markdown (default), the value will be a Markdown string. See the Data Output documentation for details on the Markdown syntax used by Lexical. If it is set to html, the value will be an HTML string.

If the required option is set to false and the field is left empty, the value will be an empty string.

When using the Markdown format, you need to parse the Markdown string using a Markdown parser in your framework to convert it to HTML for rendering on your website. Some frameworks have built-in support for Markdown, while others may require additional libraries. Please refer to your framework’s documentation on how to handle Markdown content. See also the how-to for advice on handling line breaks in Markdown.

When using the HTML format, the value can be rendered on your website as is. Make sure to sanitize it first if untrusted users can edit the content.

Future Plans

We plan to add features specific to HTML content in future releases, including text alignment, link targets, and more.

Data Validation

• If the required option is set to true, the rich text content must not be an empty string.
• If the pattern option is provided, the rich text content must match the specified regular expression pattern.

Options

In addition to the common field options, the Markdown field supports the following options:

Required Options

widget

• Type: string
• Default: string

Must be set to richtext.

Optional Options

Breaking changes from Netlify/Decap CMS

Sveltia CMS has changed the default value of the sanitize_preview option to true for improved security. In Netlify CMS and Decap CMS prior to 3.13.0, the default is false, which may expose users to XSS vulnerabilities.

Also, Sveltia CMS does not support the deprecated camelCase editorComponents option. Use editor_components instead.

format

• Type: string
• Default: markdown

Specifies the data format of the content. Possible values are markdown and html. This option is not available for the Markdown field type, which always saves Markdown.

With the html format, the editor works as follows:

• The raw mode shows the HTML source with syntax highlighting. The formatting buttons and editor components are hidden in this mode, as they insert Markdown.
• Only the editor components that support HTML are available. The built-in code-block and image components do, so images can be inserted, pasted and dropped as usual, while a custom component needs the htmlSelector, fromBlockHTML and toBlockHTML properties.
• HTML containing an element the rich text editor cannot handle, such as <video> without a component for it, can only be edited in the raw mode.
• An existing value is kept as is until the content is changed in the rich text mode. Then the editor writes HTML in its own style, such as <strong> for <b>, and attributes it doesn’t use, such as class, are dropped.

default

• Type: string
• Default: ""

The default content for the field, written in Markdown or HTML depending on the format option.

minimal

• Type: boolean
• Default: false

Whether to limit the editor height. When set to true, the editor height is limited to 240 pixels and a scrollbar appears when the content exceeds the height.

modes

• Type: array
• Default: [rich_text, raw]

The modes available in the editor. Possible values are rich_text and raw. The raw mode allows users to edit the raw Markdown or HTML text.

The following configurations are possible:

• Default modes: [rich_text, raw]
• Turn on raw mode by default: [raw, rich_text]
• Rich text only: [rich_text]
• Raw mode only: [raw]

If multiple modes are enabled, the first one is selected initially, and users can switch between them using a mode selector in the editor toolbar.

The raw mode comes with syntax highlighting for Markdown, including the code in fenced code blocks, while keeping the Markdown syntax characters visible. The toolbar buttons and editor components also work in this mode, inserting Markdown into the text. See the buttons and editor_components options below for details. With the html format, the raw mode shows the HTML source with syntax highlighting instead.

buttons

• Type: array
• Default: all available buttons (see below)

The button names to display in the editor toolbar.

The following buttons are available in the rich text editor toolbar:

• Inline formatting: bold, italic, strikethrough, code, link
• Block types: heading-one, heading-two, heading-three, heading-four, heading-five, heading-six, bulleted-list, numbered-list, quote

By default, all buttons are enabled. You can customize the toolbar by specifying the desired buttons in the buttons option.

Note for Netlify/Decap CMS users

Unlike Netlify/Decap CMS, all the block type buttons are available under the block type selector in Sveltia CMS. Users can select the block type from a dropdown menu rather than having separate buttons for each block type.

In raw mode, the buttons insert Markdown instead:

• The inline formatting buttons wrap the selected text with the corresponding Markdown syntax, such as ** for bold, or remove it if the text is already formatted. The Ctrl+B/Command+B and Ctrl+I/Command+I keyboard shortcuts are also available.
• The link button opens a dialog to insert a Markdown link, using the selected text as the link text. The Ctrl+K/Command+K keyboard shortcut is also available.
• The block type selector changes the selected lines to headings, lists, a quote or a code block, and shows the block type of the line where the cursor is.

These edits can be undone with the browser’s standard undo command, just like typing.

editor_components

• Type: array
• Default: [code-block, image] plus the names of all the registered custom components

The editor component names to include in the rich text editor.

Editor components are custom blocks that can be inserted into the content. Sveltia CMS includes built-in components and also allows for custom components.

Sveltia CMS includes the following built-in editor components for the RichText field:

• code-block: Allows users to insert and format code blocks with syntax highlighting.
• image: Enables users to add images to their content, with support for uploading and selecting images from the media storage. The image can be linked or unlinked based on the linked_images option.

Both are enabled by default. You can disable them by omitting them from the editor_components option.

Editor components, including custom ones, can also be inserted in raw mode. Clicking a component button or menu item inserts the component’s Markdown at the cursor, like ![]() for an image, so users can fill in the values directly in the text. This is not available with the html format.

With the html format, the built-in image component is saved as an <img> element, wrapped with an <a> element if it’s linked, and custom components need to support HTML to be available.

Multiple Images

The built-in image component is designed for single-file selection. There is no option for selecting multiple images because there is no standard Markdown syntax for it. To enable multiple images, use a custom component to achieve the desired output, as shown in this example.

Note for Netlify/Decap CMS users

Unlike Netlify/Decap CMS, the code-block component in Sveltia CMS is implemented as a block type. Users can insert it using the block type selector rather than the insert button. Also, the image component is displayed as a separate button in the toolbar for easier access.

Future Plans

More built-in editor components may be added in future releases, such as table.

Developers can create custom editor components to extend the functionality of the rich text editor. Custom components can be registered globally in Sveltia CMS.

allow_nested_components

• Type: boolean | 'exclude_self'
• Default: true

Whether to allow nested rich text editor components within editor components.

• true (default): Allows all nested components, including nesting a component inside itself
• false: Disables all nested components
• 'exclude_self': Allows nested components but excludes the parent component itself. For example, if you have a “Note” component with a rich text field, you can insert other components inside it, but not another “Note” component. This prevents potential issues with regex pattern matching when a component is nested inside itself.

Regex Matching Considerations

When nesting a component inside itself (enabled with allow_nested_components: true), ensure your component’s regex pattern can correctly handle nested instances. Simple patterns may incorrectly match the opening tag of the parent with the closing tag of the nested child.

linked_images

• Type: boolean
• Default: true

Whether to allow linking images in the editor. When set to true, users can add links to images. When set to false, images will be inserted without links.

use_emoji_autocomplete

• Type: boolean
• Default: true

Whether to enable emoji autocomplete in the editor. When set to true, typing a colon followed by one or more characters, such as :smi, brings up a list of matching emojis that can be inserted into the content. The colon must be at the beginning of a line or preceded by a space or an opening bracket, so a colon in the middle of a word, as in 12:34, does not trigger the suggestions. This works in both the rich text and raw Markdown editing modes.

use_markdown_shortcuts

• Type: boolean
• Default: true

Whether to enable Markdown shortcuts while typing in the editor. When set to true, typing - or * at the start of a line creates a bulleted list, 1. creates a numbered list, > creates a blockquote, and #, ##, ### create headings. Standard keyboard shortcuts such as Ctrl/Cmd+B for bold and Ctrl/Cmd+I for italic are still enabled even when this option is false.

sanitize_preview

• Type: boolean
• Default: true

Whether to sanitize the preview content to prevent cross-site scripting (XSS) attacks. The sanitization process uses DOMPurify to remove potentially harmful HTML tags and attributes from the content before rendering the preview.

Security Risk

Setting the sanitize_preview option to false can expose your CMS to XSS vulnerabilities if untrusted users have access to the CMS, especially when using Open Authoring. Malicious users could inject harmful scripts into the content, which would then be executed in the browsers of anyone viewing the preview.

We recommend keeping this option enabled unless disabling it fixes a broken preview and you fully trust all users of your CMS or you’re the sole user.

Global Field Defaults

You can define default options for all RichText and Markdown fields globally using the field_defaults.richtext option at the root of your CMS configuration. This allows you to set common configurations for all RichText and Markdown fields in your CMS without having to specify them in each field definition.

The following options can be defined globally:

• format (RichText field type only)
• default
• minimal
• modes
• buttons
• editor_components
• allow_nested_components
• linked_images
• use_emoji_autocomplete
• use_markdown_shortcuts
• sanitize_preview

The following example configures all RichText and Markdown fields to use minimal: true, disables Markdown shortcuts, and enables only the bold, italic, and link buttons by default.

YAML

field_defaults:
  richtext:
    minimal: true
    use_markdown_shortcuts: false
    buttons: [bold, italic, link]

TOML

[field_defaults.richtext]
minimal = true
use_markdown_shortcuts = false
buttons = ["bold", "italic", "link"]

JSON

{
  "field_defaults": {
    "richtext": {
      "minimal": true,
      "use_markdown_shortcuts": false,
      "buttons": ["bold", "italic", "link"]
    }
  }
}

JavaScript

{
  field_defaults: {
    richtext: {
      minimal: true,
      use_markdown_shortcuts: false,
      buttons: ["bold", "italic", "link"],
    },
  },
}

Examples

Standard Markdown Field

This example shows a basic Markdown editor with default settings.

YAML

- name: body
  label: Body
  widget: richtext

TOML

[[fields]]
name = "body"
label = "Body"
widget = "richtext"

JSON

{
  "name": "body",
  "label": "Body",
  "widget": "richtext"
}

JavaScript

{
  name: "body",
  label: "Body",
  widget: "richtext",
}

Standard HTML Field

This example shows a rich text editor that saves content in HTML format.

YAML

- name: body
  label: Body
  widget: richtext
  format: html

TOML

[[fields]]
name = "body"
label = "Body"
widget = "richtext"
format = "html"

JSON

{
  "name": "body",
  "label": "Body",
  "widget": "richtext",
  "format": "html"
}

JavaScript

{
  name: "body",
  label: "Body",
  widget: "richtext",
  format: "html",
}

Basic Markdown Field with Limited Buttons

This example shows a minimal Markdown editor with only bold, italic, and link buttons.

YAML

- name: content
  label: Content
  widget: richtext
  default: To get started, write your **Markdown** content here.
  minimal: true
  buttons: [bold, italic, link]

TOML

[[fields]]
name = "content"
label = "Content"
widget = "richtext"
default = "To get started, write your **Markdown** content here."
minimal = true
buttons = ["bold", "italic", "link"]

JSON

{
  "name": "content",
  "label": "Content",
  "widget": "richtext",
  "default": "To get started, write your **Markdown** content here.",
  "minimal": true,
  "buttons": ["bold", "italic", "link"]
}

JavaScript

{
  name: "content",
  label: "Content",
  widget: "richtext",
  default: "To get started, write your **Markdown** content here.",
  minimal: true,
  buttons: ["bold", "italic", "link"],
}

Disabling Code Block Component

This example shows how to disable the code-block editor component.

YAML

- name: content
  label: Content
  widget: richtext
  editor_components: [image]

TOML

[[fields]]
name = "content"
label = "Content"
widget = "richtext"
editor_components = ["image"]

JSON

{
  "name": "content",
  "label": "Content",
  "widget": "richtext",
  "editor_components": ["image"]
}

JavaScript

{
  name: "content",
  label: "Content",
  widget: "richtext",
  editor_components: ["image"],
}