[Spec] Custom block node

[js87zz]

Custom block node

The TOAST UI Editor has previously provided the option of customizing html, a markdown parsing result. However, our markdown parser has had some problems expanding because it follows the commonmark specification. It was difficult to define and use our own syntax that was not formally supported by commonmark. For example, drawing charts like chart plugin, summary, details block, and even latex plugin. The compatibility with WYSIWYG was also extremely hassle (and of course this is a complex issue).

In v2.x, custom syntax was supported by extending code block to force DOM updates, and chart plugin worked in this way.
But this approach was inefficient by post-processing of already rendered code block, and internal code was also very complex and difficult to maintain clearly.

We decided to create a custom node with our own syntax to fundamentally solve this problem. In addition, it provides a variety of extensions, allowing users to use it as a markdown text in a particular format. The compatibility with WYSIWYG is also more declarative and concise than before, using an abstracted model of prosemirror. As before, the spaghetti code that manipulates the DOM has disappeared.

Basic Usage

You can use the customHTMLRenderer option in key-value object to define your custom block as before.
The following code is a basic example of using customHTMLRenderer option for latex.

<script src="https://cdn.jsdelivr.net/npm/latex.js/dist/latex.js"></script>
// ...
const renderers = {
  latex(node) {
    const generator = new latexjs.HtmlGenerator({ hyphenate: false });
    const { body } = latexjs.parse(node.literal, { generator }).htmlDocument();

    return [
      { type: 'openTag', tagName: 'div', outerNewLine: true },
      { type: 'html', content: body.innerHTML },
      { type: 'closeTag', tagName: 'div', outerNewLine: true }
    ];
  },
}

const editor = new Editor({
  el: document.querySelector('#editor'),
  customHTMLRenderer: renderers,
  // ...
});

If we set the following markdown content,

$$latex
\documentclass{article}
\begin{document}

$
f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \, d\xi
$
\end{document}
$$

It is very simple to use. If you write it according to the syntax you define in the '$$' symbol, it renders it accordingly. The important point is that the name of the nodes you define must be clearly written to work (like the language info of the code blocks). The parsing operation can be configured as 'customHTMLRenderer' above.

The final HTML content will be like below.

WYSIWYG

In WYSIWYG, it is rendered as follows. As before, there is no more strange UI with modal.

v2.x

v3.0

In 3.0, you can edit it directly from a separate editor when you press the button. It is noteworthy that WYSIWYG also edits text like Markdown. This is because our editor is based on markdown, and according to the customHTMLRenderer we defined, it is reasonable to perform these operation.

TODO

• Currently, chart and UML plugins in v3.0 have been changed to this syntax. In addition, we will extend our plugin using this specification like as latex, summery, and detail, toc and etc.
• We considered only block nodes to customize. It will also add extensions to the custom inline node.
• There is no action to add custom block nodes in WYSIWYG yet. This will be considered either as a separate command or by adding menus to the toolbar.

Welcome to Feedback!! :)