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:

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: "shortcode",
    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

Shortcode in the CMS

The shortcode appears in the CMS as any other custom markdown embed. To inspect the shortcode in the CMS, use the raw markdown option in the editor.

Last Edited: September 17, 2024