Diagramas Mermaid

Escreva fluxogramas, diagramas de sequência, gráficos de pizza e gráficos de Gantt como texto Mermaid, e o editor os desenha como um bloco no documento. O Mermaid em si não faz parte do editor: a sua página o carrega, ou o seu servidor renderiza o diagrama.

Ative o recurso

O recurso é o plugin mermaiddiagram.js (também incluído em plugins/all_plugins.js). O item da barra de ferramentas é insertdiagram (dica de ferramenta "Diagram"). A barra de ferramentas padrão o traz no menu "More" (⋮); na sua própria barra de ferramentas, adicione insertdiagram. Para desenhar diagramas no navegador, carregue o Mermaid antes de criar o editor:

<link rel="stylesheet" href="/richtexteditor/rte_theme_default.css" />
<script src="https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.min.js"></script>
<script src="/richtexteditor/rte.js"></script>
<script src="/richtexteditor/plugins/mermaiddiagram.js"></script>

<div id="div_editor1"><p>How a change ships:</p></div>
<script>
mermaid.initialize({ startOnLoad: false });
var editor1 = new RichTextEditor("#div_editor1", {
  toolbar: "custom",
  toolbar_custom: "{bold,italic,underline}|{insertdiagram}|{undo,redo}"
});
</script>

De onde vem o desenho

O plugin não carrega nada da rede. Para cada diagrama, ele usa a primeira destas opções que estiver disponível:

1. diagramResolver, a sua função. Ela recebe o código-fonte Mermaid e retorna uma Promise de { svg: "<svg…" } ou { imageUrl: "…" }. Use-a para renderizar no seu servidor (por exemplo, com Kroki ou mermaid-cli).
2. window.mermaid na página (ou na janela pai dela). O plugin lida tanto com o mermaid.render antigo, que retorna uma string (versões 8 e 9), quanto com o que retorna uma Promise (10 e posteriores); estas páginas foram testadas com a 11.4.1.
3. Nenhuma das duas: o bloco mostra o código-fonte como código, e a caixa de diálogo diz "No Mermaid renderer detected on the page". O código-fonte é mantido, então o diagrama pode ser desenhado depois.

Opções

Opção	Padrão	O que faz
diagramResolver	null	O seu renderizador, usado antes de window.mermaid. Se ele rejeitar, o código-fonte é exibido com a mensagem de erro.
diagramSamples	Quatro exemplos: um fluxograma (graph TD), um sequenceDiagram, um pie e um gantt	Os botões de exemplo da caixa de diálogo. Cada botão mostra a primeira linha do seu exemplo.
text_insertdiagram, text_insertdiagramtitle, text_insertdiagramlabel, text_insertdiagrampreview	"Diagram", "Insert / edit diagram", "Mermaid", "Preview"	Dica de ferramenta do botão, título da caixa de diálogo e rótulos.

Um resolver no servidor fica assim (a URL é sua):

diagramResolver: function (source) {
  return fetch("/api/diagram", { method: "POST", body: source })
    .then(function (r) { return r.text(); })
    .then(function (svg) { return { svg: svg }; });
}

Como usar

• Clique no botão, chame editor1.execCommand("insertdiagram") ou escolha "Diagram" no menu de barra. Digite ou escolha um exemplo e clique em Insert.
• Edição. Clique duas vezes em um diagrama para reabrir a caixa de diálogo com o código-fonte dele; o botão então passa a se chamar Update.
• Remoção. Passe o mouse sobre o bloco e clique no × redondo no canto, ou pressione Delete ou Backspace com o cursor no bloco.
• Erros. Se o Mermaid não conseguir interpretar o código-fonte, a prévia mostra o código-fonte e a mensagem do Mermaid em vermelho ("Parse error on line 3 …").
• editor1.renderDiagrams() desenha de novo todos os blocos de diagrama e retorna quantos encontrou. Chame-o depois de setHTMLCode com um conteúdo que ainda não tenha desenho.

O que você precisa saber

• O bloco salvo mantém o código-fonte em data-diagram e o desenho dentro dele (abreviado aqui):

  <div class="rte-mermaid" data-rte-diagram="1" data-diagram="graph LR
    A[Pull request] --&gt; B{Review}
    …" contenteditable="false" style=""><button type="button" class="rte-mermaid-remove" data-rte-mermaid-remove="1" aria-label="Remove diagram" title="Remove diagram">x</button><div class="rte-mermaid-render"><svg …>…</svg></div></div>

  Com o Mermaid, o desenho é SVG inline (cerca de 4 KB para o fluxograma acima); sem ele, um <pre class="rte-mermaid-src">.
• O botão × de remover é salvo junto com o conteúdo. Oculte-o onde você exibe o HTML, ou ele aparece como um "x" na sua página.
• Depois que um diagrama é editado com Update, o data-diagram dele fica codificado em HTML duas vezes (--> é armazenado como -->). O editor lê as duas formas, mas o seu próprio código precisa decodificar o valor mais uma vez.
• O estilo de moldura do bloco só existe dentro do editor. Para exibir os diagramas salvos, oculte o botão e desenhe a partir do código-fonte; isto funcionou tanto para blocos novos quanto para blocos editados:

  <style>.rte-mermaid-remove { display: none; }</style>
  <script src="https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.min.js"></script>
  <script>
  mermaid.initialize({ startOnLoad: false });
  function decode(s) {
    return s.replace(/&quot;/g, '"').replace(/&gt;/g, ">").replace(/&lt;/g, "<").replace(/&amp;/g, "&");
  }
  document.querySelectorAll(".rte-mermaid[data-diagram]").forEach(function (block, i) {
    var target = block.querySelector(".rte-mermaid-render") || block;
    mermaid.render("saved-diagram-" + i, decode(block.getAttribute("data-diagram")))
      .then(function (result) { target.innerHTML = result.svg; });
  });
  </script>

• Os sanitizadores precisam manter os atributos da div acima e permitir SVG inline, ou removê-lo e desenhar de novo a partir de data-diagram, como mostrado.
• O mermaid.min.js 11.4.1 tem cerca de 2.6 MB. Carregue-o apenas nas páginas que editam ou exibem diagramas, e hospede-o você mesmo se a página precisar funcionar offline.

Relacionados: demonstração de diagramas, referência de itens da barra de ferramentas.