rich-text

Tina's rich-text field leverages MDX so you can embed your own structured blocks. To render a rich-text field with React we recommend the <TinaMarkdown> component from tinacms. See usage for details.

type RichTextField = {
  label: string
  name: string
  type: 'rich-text'
  templates: Template[]
}

Examples

Tina will generate the appropriate component depending on the configuration provided.

Simple

{
  label: "Body",
  name: "body",
  isBody: true,
  type: "rich-text",
}

Toolbar Override

Change what you want to display and the order it is displayed in the editor

{
  label: "Body",
  name: "body",
  isBody: true,
  type: "rich-text",
  toolbarOverride: ["heading","bold", "italic"],
}

Custom custom templates

{
  label: "Body",
  name: "body",
  isBody: true,
  type: "rich-text",
  templates: [
    {
      name: "Cta",
      label: "Cta",
      fields: [{
        name: "heading",
        label: "Heading",
        type: "string"
      }
    ]}
  ]
}

Given a markdown file like this:

## Hello, world!

This is some text

<Cta heading="Welcome" />

Results in the following response from the content API:

Using TinaMarkdown

The <TinaMarkdown> component allows you to control how each element is rendered. You must provide a component for each template registered in the templates property of your field definition. Note that you can also control rendering of built-in elements like <h1>, <a>, <img>

type TinaMarkdown = ({
  // The rich-text data returned from the content API
  content: TinaMarkdownContent
  /**
   * Any templates provided in the rich-text field.
   * Optionally, most elements (ex. <a>) can also
   * be overridden
   */
  components?: Components<{}>
}) => JSX.Element

import { TinaMarkdown } from 'tinacms/dist/rich-text'

// The `props` here are based off our custom "Cta" MDX component
const Cta = (props) => {
  return <h2>{props.heading}</h2>
}

export default function MyPage(props) {
  return (
    <div>
      <h1>{props.data.post.title}</h1>
      <TinaMarkdown components={{ Cta }} content={props.data.post.body} />
    </div>
  )
}

Caveats

Since markdown and MDX are traditionally handled through some sort of build step, Tina's approach adds some constraints to make things work as expected. Read more about Tina's approach to handling markdown and MDX.

All content must be serializable

When we say serializable, we mean that they must not be JavaScript expressions that would need to be executed at any point.

• No support for import/export
• No support for JavaScript expressions (eg. const a = 2, console.log("Hello"))

For example:

## Today is {new Date().toLocaleString()}

This expression will be ignored, instead register a "Date" template:

## Today is <Date />

Then you can create a Date component which returns new Date().toLocaleString() under the hood.

All JSX must be registered as a template

In the above example, if you failed to add the Cta template in your schema definition, the JSX element will be treated as html

Handling markdown

Since markdown is an open-format Tina does its best to handle the most common syntax's, but in some scenarios Tina will ignore or automatically alter content:

Unsupported elements

While most markdown features are supported out of the box, Tina will ignore elements that it cannot handle. We do not expect to support the full CommonMark and GitHub Flavored Markdown specs. Be sure to voice your support for various rich-text features by reaching out through one of our community channels!

• Footnotes
• Code blocks via indentation (use ``` instead)
• Strikethrough

Automatic transforms

For some elements, Tina will automatically transform the values:

Bold and italic marks:

__Hello__

Will be transformed to:

**Hello**

Line items:

- Item 1

Will be transformed to:

* Item 1

Deeply-nested blockquotes and code blocks:

Some of the more complex nesting patterns you can do with markdown are not supported

* > My blockquote

Will be transformed to:

* My blockquote

Markdown tables

Tables are supported through a custom template which is exported from tinacms. To use it, import it and provide it as a template for your rich-text field:

import { tinaTableTemplate } from 'tinacms'

{
  type: 'rich-text',
  label: 'Body',
  name: '_body',
  templates: [
    tinaTableTemplate,
  ]
}

Render it with the table component in <TinaMarkdown>. Note that the table cell's value is a rich-text element so should be rendered with a nested <TinaMarkdown> component:

const MyTable = props => <table>
  {props.tableRows.map((tableRow) => (
    <tr>
      {tableRow.tableCells.map((tableCell) => (
        <td>
          <TinaMarkdown content={tableCell.value} />
        </td>
      ))}
    </tr>
  ))}
</table>

<TinaMarkdown components={{ table: (props) => <MyTable {...props} /> }} />

Custom shortcode syntax

If you have some custom shortcode logic in your markdown, you can specify it in the templates property and Tina will handle it as if it were a jsx element:

The following snippet would throw an error while parsing since Tina doesn't know what to do with {{}}:

{{ WarningCallout content="This is an experimental feature, and the API is subject to change. Have any thoughts? Let us know in the chat, or through one of our [community channels](/community/)!" }}

But you can tell Tina how to handle it with a template:

{
  collections: [
    {
      // ...
      fields: [
        {
          type: 'rich-text',
          name: 'body',
          templates: [
            {
              name: 'WarningCallout',
              label: 'WarningCallout',
              match: {
                start: '{{',
                end: '}}',
              },
              fields: [
                {
                  name: 'content',
                  label: 'Content',
                  type: 'string',
                  required: true,
                  ui: {
                    component: 'textarea',
                  },
                },
              ],
            },
          ],
        },
      ],
    },
  ]
}

Raw strings in shortcodes

Certain frameworks support shortcodes with Raw string values:

{{<  myshortcode "This is some raw text" >}}

This is supported in Tina with the special _value field.

fields: [
  {
    type: 'rich-text',
    name: 'body',
    templates: [
      {
        name: 'myshortcode',
        label: 'myshortcode',
        match: {
          start: '{{',
          end: '}}',
        },
        fields: [
          {
            name: '_value',
            label: 'value',
            type: 'string',
            required: true,
          },
        ],
      },
    ],
  },
]

Nesting content in a shortcode.

Shortcodes can provide a children field, which allows content to be nested within a shortcode.

{{% shortcode %}}
What up!
{{% /shortcode %}}

Your field template definition would look something like:

{
  name: "pull_quote2",
  label: "pull_quote2",
  match: {
    name: "pull-quote",
    start: "{{%",
    end: "%}}"
  },
  fields: [
    {
      name: "children",
      type: "rich-text"
    }
  ]
}

Note: the children type currently needs to be of type: `rich-text`.

Using shortcode names with dashes.

Sometimes your shortcode will contain characters that aren't supported in Tina's content modelling

{{% my-shortcode %}}

You can supply a name on the match object to handle this.

fields: [
  {
    type: 'rich-text',
    name: 'body',
    templates: [
      {
        name: 'myshortcode',
        label: 'myshortcode',
        match: {
          start: '{{',
          end: '}}',
          name: 'my-shortcode',
        },
        // ...
      },
    ],
  },
]

Other notes

Full Spec

The full Tina MDX spec can be found here

Default values

If setting a default value for a rich-text field, you must provide the document AST. See example here

Last Edited: July 27, 2021