Plugin SDK

Structured Text customizations

Structured Text is a consciously simple format, with a very small number of possible nodes — only the ones that are really helpful to capture the semantics of a standard piece of content, and with zero possibility to introduce styling and break the decoupling of content from presentation.

This is generally a very good thing, as it makes working on the frontend extremely simple and predictable: unlike HTML or Markdown, you don't have to be defensive and worry about some complex nesting of tags that you'd never think it could be possible, or unwanted styles coming from the editors.

There are, however, situations where it is critical to be able to add a small, controlled set of styles to your content, to represent nuances of different semantics within a piece of content.

Adding custom styles to nodes

Let's take this article as an example:

The third paragraph is conceptually similar to the others, but it's obviously more important, and we want the reader to pay more attention to what it says.

In these cases, we can use plugins to specify alternative styles for paragraph and heading nodes using the customBlockStylesForStructuredTextField hook:

1
import { connect, Field, FieldIntentCtx } from 'datocms-plugin-sdk';
2

3
connect({
4
  customBlockStylesForStructuredTextField(field: Field, ctx: FieldIntentCtx) {
5
    return [
6
      {
7
        id: 'emphasized',
8
        node: 'paragraph',
9
        label: 'Emphasized',
10
        appliedStyle: {
11
          fontFamily: 'Georgia',
12
          fontStyle: 'italic',
13
          fontSize: '1.4em',
14
          lineHeight: '1.2',
15
        }
16
      }
17
    ];
18
  },
19
});

The code above will add a custom "emphasized" style for paragraph nodes to every Structured Text field in the project. The appliedStyle property lets you customize how the style will be rendered inside of DatoCMS, when the user selects it:

You can also use the first argument of the hook (field) to only allow custom styles in some specific Structured Text fields. If that's the case, you'll probably want to add some settings to the plugin to let the final user decide which they are:

1
customBlockStylesForStructuredTextField(field: Field, ctx: FieldIntentCtx) {
2
  const { fieldsInWhichAllowCustomStyles } = ctx.plugin.attributes.parameters;
3

4
  if (!fieldsInWhichAllowCustomStyles.includes[field.attributes.api_key)) {
5
    // No custom styles!
6
    return [];
7
  }
8

9
  return [
10
    {
11
      id: 'emphasized',
12
      node: 'paragraph',
13
      // ...
14
    },
15
  ];
16
}

The final Structured Text value will have the custom style applied in the style property:

1
{
2
  "type": "root",
3
  "children": [
4
    {
5
      "type": "paragraph",
6
      "style": "emphasized",
7
      "children": [
8
        {
9
          "type": "span",
10
          "value": "Hello!"
11
        }
12
      ]
13
    }
14
  ]
15
}

Adding custom marks

The default Structured Text editor already supports a number of different marks (strong, code, underline, highlight, etc.), but you might want to annotate parts of the text using custom marks.

An example would be adding a "spoiler" mark, to signal a portion of text that we don't want to show the visitor unless they explicitly accept a spoiler alert.

The customMarksForStructuredTextField hook lets you do exactly that:

1
import { connect, Field, FieldIntentCtx } from 'datocms-plugin-sdk';
2

3
connect({
4
  customMarksForStructuredTextField(field: Field, ctx: FieldIntentCtx) {
5
    return [
6
      {
7
        id: 'spoiler',
8
        label: 'Spoiler',
9
        icon: 'bomb',
10
        keyboardShortcut: 'mod+shift+l',
11
        appliedStyle: {
12
          backgroundColor: 'rgba(255, 0, 0, 0.3)',
13
        },
14
      },
15
    ];
16
  },
17
});

The code above will add a custom "spoiler" mark to every Structured Text field in the project. The appliedStyle property lets you customize how the style will be rendered inside of DatoCMS, when the user selects it:

The final result on the Structured Text value will be the following:

1
{
2
  "type": "root",
3
  "children": [
4
    {
5
      "type": "paragraph",
6
      "children": [
7
        {
8
          "type": "span",
9
          "value": "In the "
10
        },
11
        {
12
          "type": "span",
13
          "marks": ["spoiler"],
14
          "value": "final killing scene"
15
        },
16
        {
17
          "type": "span",
18
          "value": ", the director really outdid himself."
19
        }
20
      ]
21
    }
22
  ]
23
}

You're in charge of the frontend!

All of our Structured Text management libraries (React, Vue, etc.) allow you to specify custom rendering rules. When working with custom styles and marks, it's up to your frontend to decide how to render them!

`customBlockStylesForStructuredTextField(field: Field, ctx)`

Use this function to define a number of custom block styles for a specific Structured Text field.

Return value

The function must return: StructuredTextCustomBlockStyle[] | undefined.

Context object

The following properties and methods are available in the ctx argument:

Hook-specific properties and methods

This hook exposes additional information and operations specific to the context in which it operates.


ctx.itemType: ItemType

Structured Text customizations

Adding custom styles to nodes

Adding custom marks

customBlockStylesForStructuredTextField(field: Field, ctx)

Return value

Context object

customMarksForStructuredTextField(field: Field, ctx)

Return value

Context object

`customBlockStylesForStructuredTextField(field: Field, ctx)`

`customMarksForStructuredTextField(field: Field, ctx)`