Structured text fields

    Structured Text is a field type that enables authors to create rich text content.

    • it offers a beautiful, Notion-like editor designed for focus, with slash commands, markdown/keyboard shortcuts, and drag & drop. Forget the mouse, and just start typing;

    • it allows you to create hyperlinks to other records in your project, and intersperse textual content with custom blocks - which can represent galleries, videos, embeds, call-to-actions, etc.

    • it stores the content in a safe, semantic and readable JSON format, representing a tree of well-defined nodes.

    Backstory

    Everyone hates HTML editors: developers know they produce dirty code, designers fear the introduction of unwanted styling, editors struggle to use them. Markdown is better for designers, as it allows less freedom for editors from a formatting standpoint (at least until you start inserting HTML code), but it's not user friendly for editors, and it's an inflexible format for developers.

    Sure, DatoCMS provides both an HTML and a Markdown editor, because there are situations where they're unavoidable, but often, when a project needs rich-text, it is advisable to use Structured Text fields instead.

    Preview of the editor

    We designed the Structured Text editor to offer one of the best writing experiences in the market. It supports Slash commands, Markdown shortcuts and full-screen focus-mode. Here's a quick video of it:

    Customizing the editor

    A key aspect of Structured Text is the possibility to customize the field in a way that the authors are only exposed to relevant formatting options. For example, have fields of only paragraph tags or limit a certain kind of entries that can be hyperlinked or embedded:

    To add custom blocks to the field, follow this short video:

    Structured text on the API

    Structured Text content is stored as a JSON object. We chose unist as our base-format to benefit from its ecosystem of utilities for working with compliant syntax trees.

    The dast format clearly specifies:

    • which nodes are usable within the document;

    • for each node which are the possible children that it can contain;

    • any additional attribute that characterise each node.

    Take a look at the DatoCMS Abstract Syntax Tree specs to learn all the details

    Linking records

    Structured Text allows hyperlinking DatoCMS records in the flow of text. This allows the following scenarios:

    • Using custom link functions, like React Router links, towards a DatoCMS record.

    • Rendering a widget such as an image gallery, a product description box, a sign up form, an annotation window or basically anything else.

    The following example demonstrates an hyperlinked record and an inline record:

    Embedding blocks

    Similarly to Modular Content fields, you can also embed block records into Structured Text. Here's demonstration:

    Just like with the Modular content field, when a record is deleted, the blocks contained inside its Structured Text fields are also deleted, without leaving orphans in the process.

    Next steps