Methodox Wiki
Product documentation
Methodox Home

Dhole and Mermaid

Mermaid showed that diagrams written as text are worth having, and Dhole learned from it: its range of kinds, and its best ideas. Being like Mermaid is not Dhole's aim, though, and a Mermaid text is not a Dhole text. This page is for anybody who knows Mermaid and wants to know what carries over.

What Dhole takes

  • The kinds. Flowcharts, sequence, state, class and entity diagrams, mind maps, timelines, Gantt charts, pie, XY, quadrant and Sankey charts.
  • A thing made where it is first named, and --> for a dashed arrow.
  • * for where a state machine starts and stops, and composite states.
  • A sequence diagram's blocks as frames - loop, alt/else, opt, par/and, critical, break.
  • Gantt tasks that start after others, and milestones.

Mermaid spellings Dhole reads

Where a Mermaid spelling cannot be mistaken, Dhole reads it as Mermaid means it:

Mermaid Dhole reads it as
graph TD, flowchart LR a flowchart, with that direction
stateDiagram-v2, [*] a state diagram, and its start or end
autonumber on a sequence diagram's line of its own numbers: on
alt if
"Dogs" : 30 in a pie a slice
sankey-beta, and Coal, Power plant, 25 a Sankey diagram, and a flow
quadrant-1 to quadrant-4 the quarters, numbered as Mermaid numbers them

An entity diagram reads Mermaid's crow's feet drawn in characters as the counts they draw: ||--o{, |o--|{, }|..|| and the rest.

Where Dhole writes things differently, and why

  • One way to write a label, in every kind. Mermaid writes an arrow's label four ways depending on the kind - A -->|yes| B, A -- yes --> B, A ->> B: yes, A : yes. Dhole writes it one way: after a colon at the end of the line, A --> B: yes. A label between bars is said, with the Dhole way to write it.
  • Shapes and colours in words. Mermaid draws a shape with brackets - [(db)], {{hex}}, [/io/], ((circle)) - that have to be learned and are hard to read back. Dhole names the shape: [database], [hexagon], [io], [circle]. Colours are named the same way, [green], and are the theme's colours rather than CSS.
  • Indentation means nesting, everywhere. Mermaid closes a subgraph, a block, a class's body and a composite state with end or a brace. Dhole closes all of them by indentation, as Mermaid's own mind maps already do.
  • Problems that say where and how to mend them. Mermaid stops at the first error, with a parser's message. Dhole reads on, draws what it can, and says each problem in words with its line and its column.
  • The same picture everywhere. The same text draws the same picture on every machine, which a picture kept in a document or checked by a test needs.

What Dhole leaves out, and why

  • Styling languages - classDef, style, linkStyle, %%{init}%% and CSS. They make a diagram's look a second program inside the first. A Dhole diagram's look is its theme, and a text says only what its things mean.
  • HTML and Markdown in labels, and click handlers. A picture is not a web page, and every output Dhole has - PNG, SVG, PDF, a slide - draws the same text the same way.
  • Git graphs, C4, requirement, user journey, block, packet and architecture diagrams, and ZenUML. Each is a narrow notation with a better tool of its own, or a flowchart with a different vocabulary, and each would add words that work in one kind only.
  • Mermaid's flowchart-only arrows - -.->, --o, --x, ~~~ and links lengthened with extra dashes. Dhole has one dashed arrow, -->, and a line with no head, --; the others are said with the arrows a flowchart has.

What Dhole adds

  • Tables, boards and radar charts, from the first Dhole.
  • Several diagrams in one text, drawn side by side.
  • Gantt charts that skip weekends and holidays and draw the lines between tasks that wait for each other.
  • A mind map that hangs down as an organisation chart.
  • A sentence saying what every picture shows, for anybody who cannot see it.
  • The plotting framework's outputs and themes - and the editor's own palettes as themes.

Moving a Mermaid flowchart

graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]

becomes:

flowchart
direction: down
A: Christmas
B: Go shopping [round]
C: Let me think [diamond]
A -> B: Get money
B -> C
C -> D: One
C -> E: Two
D: Laptop
E: iPhone

The short names stay, each given its label on a line of its own; the shapes are named; the labels go after a colon; and the arrows are ->, Dhole's solid arrow, since Mermaid's --> is a solid arrow and Dhole's is dashed.