mermaid-authoring-guidelines

Mermaid authoring guidelines

Purpose. A figure in a Markdown artifact restates facts of the text in a form a reader traces at a glance, in every viewer that shows the document. This skill decides whether a figure is needed and in which form. When the form is Mermaid, it fixes how the figure is drawn: one concern, a size budget, no avoidable crossings, and nothing the text does not state. A render check runs in the two versions readers run: mermaid 11.17 (GitHub, VS Code) and 10.9 (JetBrains IDEs).

Load it before the first figure of any output, in any phase. The rules hold in any document language: scripts find caption and legend by their position, never by a word.

1. Red Flags (Anti-Rationalization)

• "A diagram means Mermaid." Step 0 comes first. A terminal shows Mermaid as code, a many-to-many relation reads better as a table, and a short chain reads better as a list.
• "One figure for the whole section is more complete." Structure, time and state in one figure produce edges nobody can follow. Split by concern; do not trim.
• "The layout engine will sort it out." dagre reduces crossings heuristically. It cannot remove the ones the graph forces (Step 4.3). Reduce, aggregate or split the graph itself.
• "I'll reorder the declarations until it looks right." Order moves nodes in some figures and not in others. Change the structure first (Step 4.7).
• "The text implies this relation, I'll add it." Draw only what a line of the text states. An invented arrow is read as a fact by the next implementer.
• "The colours explain themselves." A legend sits below the fence and names the notation this figure uses. Colour never carries a category alone.
• "It renders in my preview." GitHub runs 11.17, JetBrains 10.9, and 12.x changed every default. GitHub also redraws HTML labels in its own font after mermaid sized them (RF-23 of references/renderer-facts.md). Check both pinned versions, or write not rendered in the hand-off.
• "LR fits better." Width sets the text size: a 900 px column shrinks the text of an 1800 px figure to half. A flowchart of more than 6 nodes runs top to bottom.
• "I'll set the font and the theme for a consistent look." Mermaid blanks any theme value containing -, _, : or /, so sans-serif disappears. A fixed theme draws dark text on GitHub's dark page. Set neither.