Customize the rich-text toolbar

[jeffsee55]

We've had a lot of requests to customize the toolbar for the rich-text editor. This would be a good place to voice your opinion on what you might like to customize and perhaps how you'd like the API to look. In general, it'll probably need to be something you define on a rich-text field, but we don't have specific plans for anything yet. Some common requests:

• Change the order of items in the toolbar
• Remove items that you're not using
• Add custom items

At a basic level, the API could be pretty simple, just provide a callback function for the items, but curious to get more use-cases to inform this API a bit.

{
  type: 'rich-text',
  name: 'body',
  ui: {
    toolbar: (items) => items.filter(item => item.name !== 'link')
  }
}

[konsumer]

I think it would be rad if the full plate object were exposed in addition/instead, so we could change the full config. While the above would be handy & simple, I could do similar with the plate object I think, and it would allow me to do things like add more plate plugins (to process input, etc.)

{
  type: 'rich-text',
  name: 'body',
  ui: {
    plateConfig: (plate) => {
      // do anything
      return plate
    }
  }
}

maybe run this after tina configures it, so the config can be modified?

[konsumer]

Yeh, I understand that for sure. With this kind of stuff, I love having the (not recommended) option if I need to do something advanced (and possibly breaking.) In my situation, I have MDX components for images that add other stuff like image dimensions. Right now I can put the image stuff in the "Embed" menu with templates + MDX, and hide the original button with CSS, but if a user pasted HTML with an image in there, it would break, and they'd have no way to edit the image. If I could instead make all images inserted just work how I want, then I could keep the original image button, and people could safely paste word docs or web-pages with images in them.

[konsumer]

Actually, it looks like it currently strips images anyway, so maybe it is a moot-point.

custom-editor.mov

[jeffsee55]

I was going to say, we haven't added support for serializing copy/paste, that's well supported from plate though, and there is an opportunity to translate that to whatever shape you'd like but I haven't looked into it much honestly.

[konsumer]

I have used plate a bit in the past, and it can do a ton of other cool stuff (like the DnD block element stuff is really cool.) It's for sure a can-of-worms, and my original situation is totally solved, now that I look closer at it, so it's probably fine. I do occasionally find there is some kind of save-blocking semantic errors (like you can't put X inside a link) that happen sometimes on paste, that are impossible to fix (like even if you backspace over content, and try to put in regular text) but I can live with that, and that might be a lower-level problem that should be addressed with tina's default setup.

[konsumer]

The basic trick, if anyone wants to do similar in their schema, is to make a field like this:

const richRichText = {
  type: 'rich-text',
  label: 'Body',
  name: 'body',
  required: true,
  templates: [
    {
      name: 'Button',
      label: 'Button',
      fields: [
        {
          name: 'text',
          label: 'Text',
          type: 'string',
          placeholder: 'LEARN MORE'
        },
        {
          name: 'href',
          label: 'URL',
          type: 'string',
          placeholder: '#contact'
        }
      ]
    },
    {
      name: 'Image',
      label: 'Image',
      fields: [
        {
          name: 'src',
          label: 'Image',
          type: 'image',
          ui: {
            validate: (value, allValues, meta, field) => {
              if (value) {
                const i = new Image()
                i.onload = () => {
                  allValues.width = i.naturalWidth
                  allValues.height = i.naturalHeight
                }
                i.src = value
              }
            }
          }
        },
        {
          name: 'width',
          label: 'Width',
          type: 'number',
          ui: {
            component: () => null
          }
        },
        {
          name: 'height',
          label: 'Height',
          type: 'number',
          ui: {
            component: () => null
          }
        }
      ]
    }
  ]
}

then later do something like this to display the 2 components:

const components = {
  Button: ({ type, href = '#contact', text = 'LEARN MORE', ...props }) => <a href={href} className='button' {...props}>{text}</a>,
  Image: ({ type, ...props }) => <img {...props} />
}

// ...

<TinaMarkdown components={components} content={body} />

And I hide original toolbar image button it in CSS, like this:

.with-toolbar > .sticky > .grid > .grid span:nth-child(3) {
  display: none !important;
}

It outputs stuff like this in the mdx:

<Image src="/uploads/accurate-data.svg" width={535} height={375} />
<Button text="CONTACT US" />

A terrible hack, I know, but it works ok for me.

[mAAdhaTTah]

I'll also add #3058 has some thoughts dealing with inline elements. As mentioned in that issue, adding marks gets gnarly because it also affects serialization to the underlying MDX format, so if you're going to allow users to customize the marks, they also need to hook into that step as well.

[mAAdhaTTah]

Plate's deserializeMd uses remark to parse markdown straight to Slate. If we converted the mdx package to be something similar, where the conversion from markdown -> Plate was all handled through remark + plugins, customizing the rich text editor could be a combination of registering plugins with Plate & remark that handle the feature you want to implement.

[jeffsee55]

If we converted the mdx package to be something similar,

We are leveraging remark plugins for almost everything except for actually compile MDX (since we serve the AST over GraphQL instead). That said, until recently that was all backend code, we haven't shipped this yet, but we do have support for "raw" mode https://www.loom.com/share/45b6277d4dd6481fa5502ebe19a94132. Which could also be used to handle copy/paste deserializing.

Is that what you had in mind?

[mAAdhaTTah]

That seems like solving a different problem.

The way I understand the architecture, you have a couple layers. If we start in the browser, we have a rich text editor & toolbar UI. As the user edits in that rich text editor, it produces a Slate AST representing what was input. That gets sent to the GraphQL endpoint, which uses the @tinacms/mdx package to stringify that to MDX, the at-rest serialization format. Between those two steps, the mdx package translates the Slate AST to a Remark AST, which is then stringified. In reverse, it goes from MDX -> Remark AST -> Slate AST -> Editor.

If we want to add new toolbar, we need to add support throughout that whole process. Adding a Plate plugin handles the editor + Slate AST part of things, but the way the parse/stringify architecture is currently set up, translating between Remark AST & the Slate AST is pretty custom in both directions.

The link I shared is to point out that there's a Remark plugin that will translate the Remark AST to the Slate AST with some configuration. Ostensibly (because I don't really know the Remark plugin api or ecosystem), it should be feasible for the current Remark <-> Slate translation to be done as one or several Remark plugins.

If we do that, then adding a new mark or leaf or even element would be a matter of:

1. Adding a Plate plugin (custom or otherwise). This handles adding things to the Editor, as well as the associated Slate AST.
2. Adding a Remark plugin. This would handle the translation between Remark <-> Slate ASTs, with Remark still handling the stringification.

That's at least the idea. As I said, I don't have a deep knowledge of Remark, so I don't know how feasible this actually is, or how their plugin API works. If it is possible though, it would allow Tina to push off a lot of work to those ecosystems & their APIs rather than needing to design a plugin API for a custom parse/stringify flow.

(Some slight edits to include the editor itself in my understanding of the flow.)

[jeffsee55]

there's a Remark plugin that will translate the Remark AST to the Slate AST

Maybe I'm missing something here, but it seems like we'd have to write any logic introduced by a remark plugin. For example the remark-footnotes would give us this shape, which remark-slate knows nothing about:

This is a sentence with a footnote.[^1]

[^1]: And this is a footnote.

{
  type: 'root',
  children: [
    {
      type: 'paragraph',
      children: [
        {
          type: 'text',
          value: 'This is a sentence with a footnote.',
        },
        {
          type: 'footnoteReference',
          identifier: '1',
          label: '1',
        },
      ],
    },
    {
      type: 'footnoteDefinition',
      identifier: '1',
      label: '1',
      children: [
        {
          type: 'paragraph',
          children: [
            {
              type: 'text',
              value: 'And this is a footnote.',
            },
          ],
        },
      ],
    },
  ],
}

footnoteDefinition and footnoteReference would need to be handled by something that knows it should be turned into this (for example). I expect we'd still have to write that logic:

{
  type: 'root',
  children: [
    {
      type: 'p',
      children: [
        {
          type: 'text',
          text: 'This is a sentence with a footnote.',
        },
        {
          type: 'footnoteReference',
          identifier: '1',
          label: '1',
        },
      ],
    },
    {
      type: 'footnoteDefinition',
      identifier: '1',
      label: '1',
      children: [
        {
          type: 'p',
          children: [
            {
              type: 'text',
              text: 'And this is a footnote.',
            },
          ],
        },
      ],
    },
  ],
}

And then the easy part would be registering footnoteDefintion and footnoteReference as plate plugins.

Sorry if I'm talking across you, just want to make sure I understand. I initially tried using remark-slate but it fell short for our needs in a few ways.

[mAAdhaTTah]

No worries! A lot of this is borne of my own ignorance of Remark itself, so definitely correct me if I'm missing something here. I don't necessarily think remark-slate would cover everything. It's more of an inspiration.

The overall idea is for Remark to provide the plugin API needed to make this all feasible. Instead of needing to design a Tina Plugin API for the Editor, that API is a set of hooks for someone to register a Plate plugin & a Remark plugin together, keeping Tina's logic pretty thin. So my expectation is you (or whoever wants footnotes, like me) would need to write the logic to translate between the two as a Remark plugin. You wouldn't necessarily just install remark-footnotes and be done. You would need to write a second plugin that takes the Remark footnotes AST and converts it to the Slate AST.

I don't actually know if this is possible with Remark, or remark-slate, or whatever. I'm mostly proposing this as a simplification so Tina doesn't have to implement its own custom Editor Plugin API.

[robbyph]

How do the buttons on the bar work now? Are the existing buttons basically 'built in' embeds?

[konsumer]

They are pre-defined plate plugins that register a button (and it's associated action, like "insert an a tag".) You can see the examples here: https://plate.udecode.io/ Here is a nice "kitchen sink": https://plate.udecode.io/docs/playground

[jeffsee55]

Yeah we're mostly using things straight from plate, but we're providing our own UI for it all

https://github.com/tinacms/tinacms/blob/main/packages/%40tinacms/toolkit/src/packages/fields/plugins/MdxFieldPlugin/plate/plugins/ui/toolbar/index.tsx#L107.

[cereallarceny]

I would absolutely love this feature to be added. Quite frankly, I just asked a question about this in Discord, only to find the discussion happening here.

[jaschaio]

Any update here? Three of the most basic use cases I can think of are footnotes, strike through and highlighting (e.g. <mark></mark>)

[DmacMcgreg]

Hey now that we've got some fresh updates going on here, it would be really great to have custom buttons like superscript, subscript, footnotes... etc.