Rich Text (v2) and Markdown Field Types | Yext Hitchhikers Platform

New Release Feature

This documentation references the new Rich Text (v2) and Markdown Field Types feature. To turn this feature on in your account, navigate to Account Settings > Account Features and select Summer ‘23: Rich Text (v2) and Markdown Field Types Updates (early access).

This reference provides details about both the Rich Text (v2) and the Markdown field types, including supported formatting, storage format, ingesting and exporting content, and known limitations.

Rich Text (v2)

The Rich Text (v2) field type offers a WYSIWYG editor with support for a wide variety of formatting.

• Target Use Case: This field type is intended primarily for authoring formatted content.
• Target Audience: This field type is suitable for use by all content managers, regardless of technical abilities.

Supported Formatting

The following is the current list of supported formatting options in the Rich Text (v2) field type.

Storage Format

The underlying storage format of the Rich Text (v2) field type is a JSON Abstract Syntax Tree (AST). This storage format is based primarily on the library that the system leverages, which is Lexical.dev.

Most modern rich text editors use an AST as their storage format, as this structured format makes working with formatted content in code much simpler, and ensures that the types of supported formatting can be expanded over time.

Because the storage format is an AST, importing and exporting content to the Rich Text (v2) field type requires processing to/from the AST. This import and export process is covered in detail below.

Object Structure

In code interfaces, Rich Text (v2) type fields are represented as a structured object with a sub-property called json, where the AST is included. The following is an example of a simple Rich Text (v2) field (c_richTextv2Description) as returned by the Content API.

{
 "id": "product-1",
 "name": "Product 1",
 "c_richTextv2Description": {
   "json": {
     "root": {
       "children": [
         {
           "children": [
             {
               "detail": 0,
               "format": 1,
               "mode": "normal",
               "style": "",
               "text": "bold text",
               "type": "text",
               "version": 1
             }
           ],
           "direction": "ltr",
           "format": "",
           "indent": 0,
           "type": "paragraph",
           "version": 1
         }
       ],
       "direction": "ltr",
       "format": "",
       "indent": 0,
       "type": "root",
       "version": 1
     }
   }
 }
}

As of Summer ‘23, Rich Text (v2) type fields also store a named subproperty for html. If a subproperty for plaintext would be useful to you, please leave us a note on the Ideas Board !

Importing Content to Rich Text (v2)

If you are importing content on an ongoing basis from an external source, we strongly recommend that you use the Markdown field type, not the Rich Text (v2) field type, as the Rich Text (v2) type is intended primarily for authoring in the platform.

Typically, when moving over from another source of truth, the content in that system can be exported in a standard format, such as HTML or Markdown. If you intend to manage this content outside of Yext going forward, you’ll need to supply a valid JSON AST in order to successfully import it into Yext via most ingestion layers. Converting from HTML or Markdown to an AST can be lossy. Specific tooling around conversion for each interface is covered below.

We support native transformations from HTML/Markdown to the Rich Text AST in the Connectors framework. For more information on the Connectors conversion, see the Convert to Rich Text transform documentation .

Exporting and Rendering Content From Rich Text (v2)

In order to render content from the Rich Text (v2) field type on a website, the content needs to eventually be converted into HTML. As such, we provide tooling to make this conversion task as easy and ergonomic as possible.

At this time, we support a React Component for rendering the Rich Text AST in our @yext/pages-components library . We recommend leveraging this component on any React-based front-end experiences, as it abstracts away the complexity of processing the AST.

Streams (Pages, Search, and Content API)

We currently support conversion from AST to HTML in Streams simply by indicating [richTextv2Field[“html”]]. Requesting [richTextv2Field] alone will return the AST.

Entities API

In Entities API calls, users can specify a convertRichTextToHTML parameter. By default this is false, returning the AST. Setting convertRichTextToHTML=true will return the HTML conversion of the field.

Limitations

• No Yext-provided tools for converting content from HTML/Markdown to AST via API.

Markdown

The Markdown Field Type offers a Markdown editor with a side-by-side rendered view.

• Target Use Cases:
  • This field type is intended primarily for authoring formatted content in Markdown/HTML
  • This field type is well suited when an external system is the source of truth, and the formatted content will not be managed primarily out of Yext Content, as it can ingest formatted content from external sources losslessly.
• Target Audience: This field type is suitable for use by technical content managers who prefer to author formatted content in code.

Supported Formatting

The full list of supported formatting is any formatting which is supported:

• Natively in Markdown (specifically Github-Flavored) Markdown )
• In HTML, as HTML can be included in Markdown directly as markup

Thus, this field type is guaranteed to be the most flexible, as it will support any formatting supported on the web.

Warning

Markdown inherently allows for arbitrary HTML to be stored in its content. We do not attempt to filter your content in any way upon ingestion. If you convert to HTML when you retrieve your content we handle sanitization in the conversion.

If you are intending to retrieve your data as Markdown and do your own conversion to HTML, make sure you are implementing a library that ensures that malicious scripts are not executed when rendering this content. Read more here.

Storage Format

The underlying storage format of the Markdown Field Type is Github-Flavored Markdown (GFM). As mentioned above, HTML can be included in the field directly as markup.

Object Structure (Code)

In code interfaces, Markdown Field Types are represented as a structured object with a sub-property called markdown, where the Markdown is included. The following is an example of a simple Markdown field (c_markdownDescription) as returned by the Content API.

{
 "id": "product-1",
 "name": "Product 1",
 "c_markdownDescription": {
   "markdown": "**bold text**\n\n"
 }
}

As of Summer ‘23, Markdown type fields also store a named subproperty for html. If a subproperty for plaintext would be useful to you, please leave us a note on the Ideas Board !

Importing Content to Markdown

No conversion is needed to import content into the Markdown field type. Because the field type has a storage format of Markdown, and also accepts arbitrary HTML, any text can be stored in this field type.

Because this field type requires no conversion on-import, it is well suited for ingesting formatted content from external source systems. This import will be lossless, since the system will store the content as provided, assuming a valid string is provided.

When rendering the stored content in Entity Edit, the system leverages rehype , a JavaScript package for sanitizing HTML. This library ensures that any malicious scripts are not executed when rendering this content.

In the future, we may consider supporting some tooling to help strip out in-line CSS during ingestion, likely in the Connectors Transform layer. We understand that sometimes formatted content comes with extra styling which is unnecessary when attempting to only preserve the document structure.

Exporting and Rendering Content from Markdown

In order to render content from the Markdown field type on a website, the content needs to eventually be converted into HTML.

Since Github-Flavored Markdown is a standard format, there are a wide swath of well maintained libraries that handle converting GFM to HTML which can be leveraged to achieve this goal. For JavaScript frontends, we recommend ShowdownJS . If you choose to use Showdown, be sure to set your “flavor” to GFM.

Additionally, as mentioned above, we leverage the rehype JavaScript library to sanitize content when rendering in Entity Edit. We recommend leveraging this library, or a similar library, to sanitize your HTML; this approach will ensure your front-end matches what you see in Entity Edit, and you are protected against any scripts which might otherwise break your website.

We also have a pre-built React component which handles sanitizing and rendering Github-Flavored Markdown. You can find this component in the @yext/pages-components library .

Streams (Pages, Search, and Content API)

We currently support conversion from MD to HTML in Streams simply by indicating [richTextv2Field[“html”]]. Requesting [richTextv2Field] alone will return Markdown.

Entities API

In Entities API calls, users can specify the convertMarkdownToHTML parameter. By default this is false, returning Markdown. Setting convertMarkdownToHTML=true will return the HTML conversion of the field.

Known Limitations

• No Yext-provided tools for stripping in-line CSS when importing HTML to the Markdown field type.

Migrating from Legacy Rich Text (v1)

Follow this guide to migrate existing Legacy Rich Text (v1) fields to Rich Text (v2) or Markdown.