Typesetting math formulas with PlantUML and Mermaid

Introduction

Formulas show up in architecture diagrams more often than you would expect: the quadratic formula, a discount rule, an SLA percentage, the expected wait time of a queue. The usual workaround is plain text (x = (-b +- sqrt(b^2-4ac)) / (2a)), which is unreadable; the other extreme is pasting a screenshot, which means redrawing the picture every time one digit changes.

Both engines support LaTeX-style math natively. PlantUML goes the MathJax route: an <math>...</math> tag embedded in a class-diagram note, or a dedicated @startmath / @startlatex block for a formula-only diagram. Mermaid goes the KaTeX route: write $$...$$ inside a node label and it is typeset on render. This article draws the same quadratic formula in both engines, covers what each dialect accepts, and flags the mistake that trips up almost everyone.

PlantUML version

PlantUML’s <math> tag works anywhere text is allowed, and the most common home for it is a note. Here is a class diagram carrying the quadratic formula:

1
2
3
4
5
6
7
8
9
10
11
12

@startuml
class Quadratic {
  {field} double a
  {field} double b
  {field} double c
  {method} double root1()
  {method} double root2()
}
note right of Quadratic
  <math>x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}</math>
end note
@enduml

After rendering, the formula is not text — it is an embedded vector graphic: the fraction bar, the hook of the radical and the ± sign are all real paths.

Key points:

• The <math> tag is mandatory, and the content is LaTeX: writing $x^2$ or bare text just prints the characters verbatim — the $ triggers no typesetting on its own.

• Backslashes come in pairs: LaTeX commands such as \frac, \sqrt and \pm all start with a backslash.

• Braces group, they are not literals: in b^2 - 4ac the ^ applies only to the single character right after it; to raise a whole expression, write b^{2 - 4ac}.

• A formula-only diagram: swap the @startuml opener for @startmath (or @startlatex) and close it accordingly, and the formula gets a diagram of its own — useful when the formula is the thing being explained:

  1 2 3

  @startmath sum_(i=1)^n i = n(n+1)/2 @endmath

  Note: @startmath and @startuml cannot be mixed or nested in one file — a file renders one kind of block only.

• @startmath versus @startlatex: @startmath follows AsciiMath style, so functional notation such as sqrt(4), text(hello) and root(2) parses. @startlatex understands LaTeX syntax only (\sqrt{4}, \frac{a}{b}). Both accept \frac{a}{b} and \sqrt{4}, so @startlatex is the safer default.

Mermaid version

Formulas inside Mermaid node labels are rendered with KaTeX, following the same conventions as math in Markdown: a single dollar sign $...$ for inline math, double dollar signs $$...$$ for display math. Inside Mermaid you want $$, because the node label already sits inside quotes.

1
2
3
4
5

flowchart LR
  Q["Quadratic: ax^2 + bx + c = 0"] --> R["$$\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$"]
  R --> X1["$$x_1 = \frac{-b + \sqrt{D}}{2a}$$"]
  R --> X2["$$x_2 = \frac{-b - \sqrt{D}}{2a}$$"]
  R -.-> S["$$D = b^2 - 4ac$$"]

Key points:

• Use $$, not $: a single $...$ inside a node label does not trigger KaTeX — the formula shows up literally as $\frac{...}$. Only $$...$$ actually typesets.
• Always quote the label: R["$$...$$"] contains spaces, backslashes and braces; without quotes Mermaid’s parser truncates it or throws.
• Backslashes need no escaping in Mermaid: write \frac directly. Markdown code-block rendering does not rewrite backslashes either, so the formula survives into the published page unchanged.
• KaTeX’s capability envelope: KaTeX handles fractions, radicals, sub- and superscripts, matrices and aligned environments, but not macros that need a full LaTeX toolchain — \begin{equation} and TikZ drawings are out of reach.
• Node size follows the formula: once KaTeX renders into a foreignObject, the node width is measured from the real formula width, so a label carrying a long fraction pushes its neighbours further apart. That is normal layout, not a render failure.

Side-by-side

Which to pick: when the formula is the subject — a formula-only diagram, or AsciiMath-style functional notation — use PlantUML’s @startlatex / @startmath. When the formula is just an annotation sitting among flow arrows, Mermaid’s $$...$$ is less work, because Mermaid is designed around flow relationships in the first place.

Wrap-up

The point of math typesetting is not whether the engine can render a formula — both can — but where you put it and which dialect you speak. PlantUML treats formulas as first-class citizens: the <math> tag drops into any text position, and @startmath / @startlatex can stand alone as their own diagram. Mermaid treats a formula as label content: $$...$$ typesets inside a node, bounded by the KaTeX subset and by the label grammar. Both share a single red line — remember the wrapper: forget <math> in PlantUML or $$ in Mermaid, and all you get is a string of characters nobody can read.