View source for Help:Diagrams

This wiki can store '''diagrams as diagrams''' rather than as uploaded pictures. A diagram lives on its own page, keeps a full edit history like any other page, and can be re-opened and changed by the next person — no hunting for the original file, and no re-uploading a flat image every time something moves.

You need to be logged in and in the '''writer''' group to create or change a diagram. Anyone can view them.

== Choosing a format ==

{| class="wikitable"
! Namespace !! Best for !! How you edit it
|-
| [[#Mermaid|Mermaid:]] || Flowcharts, sequence diagrams, state machines, ER diagrams, timelines || Text — a few lines of Mermaid syntax
|-
| [[#DOT|DOT:]] || Graphs and trees: signal chains, network maps, workflows || Text — Graphviz DOT syntax
|-
| [[#Drawio|Drawio:]] || Free-form drawings, block diagrams, anything you want to drag around || Full visual editor (draw.io / diagrams.net)
|-
| [[#BPMN|BPMN:]] || Formal process diagrams, with elements that can link to wiki pages || Visual editor
|-
| [[#Gantt|Gantt:]] || Project schedules with dependencies || Visual editor
|}

'''Mermaid''' and '''DOT''' are the two most useful here for typical hardware, RF and reverse-engineering documentation, and they are the easiest to review in a diff because the source is plain text.

== Creating a diagram ==

The easiest way is to '''write a red link and click it''':

# On any page, add a link in a diagram namespace, for example <code><nowiki>[[Mermaid:Meter capture chain]]</nowiki></code>.
# Save, then click the new red link.
# The diagram editor opens directly. Fill it in and save.

You can also go straight to the editor for a page that does not exist yet by visiting its URL with <code>?action=editdiagram</code> on the end.

On a diagram page that already exists, use the '''Edit diagram''' tab at the top.

== Showing a diagram on another page ==

Diagram pages are '''not''' transcluded with the usual double braces. Use [[Template:Diagram]], naming the diagram page including its namespace:

<pre>
{{Diagram|page=Mermaid:Meter capture chain}}
</pre>

That renders the diagram inline wherever you put it, so an article can show a diagram that is maintained on its own page. Each section below gives the exact line for that format's example.

'''You do not have to type any of that.''' In the visual editor, diagrams can be added, repointed and opened for editing without touching wikitext — see [[#Using the visual editor|Using the visual editor]] below.

The older form <code><nowiki>{{#display_diagram:Mermaid:Meter capture chain}}</nowiki></code> still works and renders identically. Prefer the template: <code>#display_diagram</code> is a parser function, and the visual editor can edit a template's parameters but not a parser function's target, so bare calls can only be changed by editing the page source.

'''Highlighting one node for one page:''' Mermaid diagrams take an optional <code>style</code> parameter that restyles part of the diagram on that page only &mdash; see [[#Highlighting part of a diagram on one page|Highlighting part of a diagram on one page]].

'''One limit to know about:''' a single page can contain '''at most one BPMN or Gantt''' diagram — the extension gives both of them the same internal element name, so a second one on the same page is refused with an error message. Mermaid, DOT and Drawio can be embedded as many times as you like.

== Using the visual editor ==

''Screenshots for this section have not been uploaded yet. Each caption below names the file to upload — for example <code>FlexDiagrams VE insert template.png</code> — so uploading under that exact name fills the slot with no further edit to this page.''

Everything here works in the ordinary visual editor. Nothing below requires editing wikitext.

=== Adding a diagram to a page ===

Put the cursor where the diagram should go, then '''Insert → Template'''. Type <code>Diagram</code> and choose it.

[[File:FlexDiagrams VE insert template.png|thumb|none|700px|The Insert → Template dialog with "Diagram" typed into the search box.]]

Fill in the '''Diagram page''' field with the diagram's full page name, ''including'' its namespace prefix — <code>Mermaid:</code>, <code>DOT:</code>, <code>Drawio:</code>, <code>BPMN:</code> or <code>Gantt:</code>. The field suggests existing pages as you type, so you rarely need to type the whole name.

[[File:FlexDiagrams VE diagram field.png|thumb|none|700px|The Diagram page field, suggesting existing diagram pages as you type.]]

Insert, and save the page as usual.

=== What a diagram looks like while editing ===

An embedded diagram does '''not''' appear as a picture in the visual editor. It shows as a single labelled line naming the diagram, like:

 ◈ Mermaid:RE FlowChart Overview — diagram, edit it on its own page

[[File:FlexDiagrams VE placeholder.png|thumb|none|700px|An embedded diagram as it appears while editing: one labelled line rather than the rendered picture.]]

That is deliberate. The visual editor cannot run the diagram renderer, so without it you would see the diagram's raw source — dozens of lines of flowchart code — sitting in the middle of the article. The line above is shown instead. Save or preview the page to see the diagram itself.

=== Editing the diagram ===

'''Double-click''' the line. The diagram's own editor opens '''in a new tab''', leaving your article edit untouched in the original tab. Edit the diagram, save it there, then return to your article.

=== Changing which diagram is shown ===

'''Single-click''' the line to select it. A small box appears with two choices:

* '''Edit "…" ↗''' — opens that diagram's editor in a new tab, the same as double-clicking.
* '''Change which diagram is shown''' — opens the template's settings so you can point this embed at a different diagram page.

[[File:FlexDiagrams VE context menu.png|thumb|none|700px|Selecting an embedded diagram: edit the diagram itself, or change which diagram the page shows.]]

Single-clicking also selects the diagram as a block, so <code>Backspace</code> removes the embed from the article — which deletes only the embed, never the diagram page itself.

=== If you edit the source instead ===

The visual editor is not required. In the source editor the same embed is one line:

<pre>
{{Diagram|page=Mermaid:RE FlowChart Overview}}
</pre>

Both editors produce exactly the same thing, and you can move between them freely.

== Mermaid ==

Flowcharts, sequence diagrams, state machines, class and ER diagrams, pie charts and timelines, all written as text. Served entirely from this wiki.

'''Example page:''' [[Mermaid:Example diagram]] — [{{fullurl:Mermaid:Example diagram|action=editdiagram}} open it in the editor]

Its source is simply:

<pre>
flowchart LR
    A[Smart meter] -->|900 MHz| B(SDR capture)
    B --> C{Decodes?}
    C -->|yes| D[rtlamr output]
    C -->|no| E[Adjust gain / freq]
    E --> B
</pre>

Embed it in a page with:

<pre>
{{Diagram|page=Mermaid:Example diagram}}
</pre>

which renders as:

{{Diagram|page=Mermaid:Example diagram}}

See [https://mermaid.js.org/intro/ the Mermaid documentation] for the full syntax. This wiki bundles '''Mermaid 11.17.2''', so the Mermaid 11 diagram types — architecture, packet, kanban, treemap and radar — all work. Diagram types added in Mermaid 12 will not render, and <code>layout: elk</code> is not available (it falls back to the default layout silently).

=== How diagrams are styled ===

Mermaid diagrams on this wiki use the '''RECESSIM theme''', set once site-wide, so every
diagram looks the same without anyone having to style it: grey nodes with red borders,
black connectors, and grey subgraph containers. You do not need to do anything to get it.

Two pages exist to check the theme, because a diagram page holds exactly one diagram:

* [[Mermaid:Theme test]] &mdash; every node shape, link style and nested subgraph.
  [{{fullurl:Mermaid:Theme test|action=editdiagram}} Open in the editor]
* [[Mermaid:Theme test pie]] &mdash; a pie chart, which is the one diagram type whose
  colours come from <code>secondaryColor</code> and <code>tertiaryColor</code> rather
  than the node colours. [{{fullurl:Mermaid:Theme test pie|action=editdiagram}} Open in the editor]

Open both after any change to the site-wide theme to check nothing has broken.

==== Which shape means what ====

[[Mermaid:Theme test]] labels every shape with its meaning '''and''' the syntax that
produces it, so it doubles as a cheat-sheet. Mermaid reaches only 14 shapes through the
classic bracket syntax; the rest need <code>A@{ shape: doc }</code> form, which is where
the standard flowchart symbols live &mdash; document, manual input, display, delay, loop
limit, stored data and so on.

'''Three shapes are used differently here than in Mermaid's own documentation''', so go by
this wiki, not by the Mermaid docs:

* '''Stadium''' <code>([text])</code> &mdash; start '''and''' end of a flow.
* '''Circle''' <code>((text))</code> &mdash; a '''connector''', as in traditional
  flowcharts. Mermaid's docs call this "Start"; we do not.
* '''Double circle''' <code>(((text)))</code> and the '''asymmetric''' shape
  <code>&gt;text]</code> have '''no agreed meaning''' here. Mermaid itself describes the
  asymmetric one only as "Odd shape". They are on the test page for reference; do not use
  them to mean anything.

For the same reason, avoid the rounded rectangle <code>(text)</code> and the small/framed
circles &mdash; Mermaid assigns them Event, Start and Stop, which collide with the stadium
above. The test page marks all of these.

A diagram '''can''' override the theme for itself, with either a <code>%%{init: ...}%%</code>
directive or a YAML <code>config:</code> block at the top of its source. Be aware that doing
so makes that diagram ignore the site-wide theme '''completely''', including any later change
to it &mdash; so prefer leaving it alone unless one diagram genuinely needs to differ.

=== Highlighting part of a diagram on one page ===

An article sometimes needs to point at '''one step''' of a shared diagram without changing the diagram itself. Add a <code>style</code> parameter to [[Template:Diagram]]: its contents are added to the end of the diagram '''for this embed only'''. The diagram page, and every other page that shows it, stay exactly as they are.

<pre>
{{Diagram|page=Mermaid:RE Microscope Workflow|style=style MW_Memory_File stroke-width:8px}}
</pre>

{{Diagram|page=Mermaid:RE Microscope Workflow|style=style MW_Memory_File stroke-width:8px}}

Compare it with the unmodified [[Mermaid:RE Microscope Workflow]]: only the ''IC Data'' circle has changed. In the visual editor, the same thing is the '''Extra style (Mermaid only)''' field of the template.

* '''Use the node's id, not its label.''' Above, the id is <code>MW_Memory_File</code>; its label is ''IC Data''. Open the diagram page to find the ids.
* '''Several statements go on one line, separated by <code>;</code>''', e.g. <code>style=style MW_Memory_File stroke-width:8px; style MW_Sample-Preparation fill:#ffd</code>
* Any Mermaid flowchart statement works, not only <code>style</code> &mdash; e.g. <code>classDef hot fill:#ffd; class MW_Memory_File,MW_Sample-Preparation hot</code> to highlight several nodes the same way.
* '''A misspelled id is not reported.''' Mermaid does not complain &mdash; it draws an extra, empty node with that name. If a stray box appears, check the spelling.
* '''Mermaid only.''' On a DOT, Drawio, BPMN or Gantt page the parameter shows an error instead of the diagram.
* Editing the diagram page still updates this embed by itself, with no purge.

=== Building one diagram from several pages ===

A large flowchart can be split up so that '''each part is its own diagram page''' &mdash;
with its own editor, preview and history &mdash; while an overview page assembles them
into a '''single diagram''' at render time. Edit a part and every overview that uses it
updates by itself, with no purge.

Here are two small parts. [[Mermaid:Example part one]]:

<pre>
flowchart LR
  EX1_Start([Start]) --> EX1_Capture[/Capture signal/]
  EX1_Capture --> EX1_Decode[Decode frames]
</pre>

{{Diagram|page=Mermaid:Example part one}}

and [[Mermaid:Example part two]]:

<pre>
flowchart LR
  EX2_Analyse[Analyse payload] --> EX2_Report[[Write it up]]
  EX2_Report --> EX2_End([End])
</pre>

{{Diagram|page=Mermaid:Example part two}}

Put them together on any ordinary page with <code>&lt;composediagram&gt;</code>. Each part
gets an <code>id</code>, a <code>title</code> (the heading shown on its box) and the
<code>page</code> to read. Edges joining the parts go '''between the tags''':

<pre>
&lt;composediagram direction="TD"
 id1="EX_Capture"  title1="Capture"  page1="Mermaid:Example part one"
 id2="EX_Analysis" title2="Analysis" page2="Mermaid:Example part two"&gt;
EX_Capture --> EX_Analysis
&lt;/composediagram&gt;
</pre>

which renders as:

<composediagram direction="TD"
 id1="EX_Capture"  title1="Capture"  page1="Mermaid:Example part one"
 id2="EX_Analysis" title2="Analysis" page2="Mermaid:Example part two">
EX_Capture --> EX_Analysis
</composediagram>

A worked example with five parts is at [[User:Hash/Sandbox]].

==== Choosing how deep to draw ====

Add <code>level</code> to draw every part at a given depth, or <code>level''N''</code> to set part ''N'' on its own (it overrides <code>level</code>):

{| class="wikitable"
! Level !! What each part shows
|-
| <code>1</code> || One block with the part's title
|-
| <code>2</code> || The part's own nodes; any subgraphs inside it are drawn as titled blocks
|-
| <code>3</code>, <code>4</code>, &hellip; || One more layer of subgraphs opened at each step
|}

<pre>
&lt;composediagram direction="TD" level="1" level5="3" ...&gt;
</pre>

With no level at all, every part is drawn in full, exactly as before. Setting a part to <code>all</code> (e.g. <code>level5="all"</code>) also means full depth, which is useful when <code>level</code> sets a lower default.

* '''Empty subgraphs are placeholders''' &mdash; <code>subgraph FW_Advanced [Advanced Techniques]; end</code> &mdash; and simply stay blocks at any level until someone fills them in. No error.
* '''Edges into hidden nodes are redrawn to the block''' that now stands for them, keeping their labels, so the overview's edges can point at nodes deep inside a part and still make sense when that part is collapsed.
* Contents must be written '''inline''' in the part page; a subgraph cannot pull in another page.

Examples of each are at [[User:Hash/Sandbox#Depth levels]].

==== What you need to get right ====

# '''Each part must be a valid diagram on its own''', starting with <code>flowchart ...</code>. That header is removed when composing (it is not legal inside a subgraph) but its direction is kept, so a part laid out <code>LR</code> still runs left-to-right inside the overview.
# '''Node ids must be unique across every part.''' This is the one that bites. Give each part its own prefix &mdash; <code>EX1_</code>, <code>EX2_</code>, <code>FI_</code>, <code>ME_</code>. If two parts both declare <code>Start</code>, '''Mermaid does not report an error''': it silently merges the two boxes, keeping the position of the first and the label of the last, so one part quietly starts displaying another part's text. The tag checks for this before rendering and, if it finds a clash, shows an error naming the id and both pages instead of drawing a misleading diagram.
# '''Edges that join two parts belong in the overview''', between the tags &mdash; a part cannot refer to ids it does not contain.
# '''Do not put a <code>config:</code> or <code>%%{init}%%</code> block in a part.''' It is stripped when composing, and on the part's own page it would override the site-wide theme (see [[#How diagrams are styled]]).
# '''The subgraph <code>id</code> you choose shares the same namespace as the node ids''', so it must not collide with a node in any part either.

If a part has a syntax error, the '''overview''' is what shows the error. The composed
source carries <code>%% ___ begin <Page> ___</code> markers, so the line number in the
error message can be traced back to the part that caused it.

[[File:FlexDiagrams Mermaid editor.png|thumb|none|700px|The Mermaid editor: type the diagram source in the text box and the preview above it redraws as you type.]]

== DOT ==

Graphviz DOT source, rendered in your browser by the bundled Viz.js. You describe what connects to what and Graphviz works out the layout. Served entirely from this wiki.

'''Example page:''' [[DOT:Example diagram]] — [{{fullurl:DOT:Example diagram|action=editdiagram}} open it in the editor]

Its source:

<pre>
digraph FlashExtraction {
    rankdir=LR;
    node [shape=box];
    "Target PCB" -> "Desolder chip";
    "Desolder chip" -> "Socket adapter";
    "Socket adapter" -> "Programmer";
    "Programmer" -> "Binary dump";
    "Binary dump" -> "Analysis";
}
</pre>

Embed it in a page with:

<pre>
{{Diagram|page=DOT:Example diagram}}
</pre>

which renders as:

{{Diagram|page=DOT:Example diagram}}

[[File:FlexDiagrams DOT editor.png|thumb|none|700px|The DOT editor: Graphviz source in the text box, with the rendered graph above it.]]

== Drawio ==

The full draw.io drawing tool, for free-form diagrams you build by dragging shapes around. Good when the layout itself carries meaning — panel layouts, wiring sketches, block diagrams.

'''Example page:''' [[Drawio:Example diagram]] — [{{fullurl:Drawio:Example diagram|action=editdiagram}} open it in the editor]

Embed it in a page with:

<pre>
{{Diagram|page=Drawio:Example diagram}}
</pre>

which renders as:

{{Diagram|page=Drawio:Example diagram}}

'''One thing to know:''' the Drawio editor is loaded from the external site <code>embed.diagrams.net</code> while you are editing. Your diagram is saved here on the wiki, not on their servers, and viewing a saved Drawio diagram does not contact them at all — but ''editing'' one needs that external site reachable from your browser. The other four formats are served entirely from this wiki.

[[File:FlexDiagrams Drawio editor.png|thumb|none|700px|The Drawio editor: the full draw.io canvas, shape palette and format panel, embedded in the wiki page.]]

== BPMN ==

Formal business-process diagrams, drawn with bpmn-js. Worth knowing: an element named <code><nowiki>[[Some page]]</nowiki></code> becomes a link to that wiki page, so a process diagram can double as navigation.

'''Example page:''' [[BPMN:Example diagram]] — [{{fullurl:BPMN:Example diagram|action=editdiagram}} open it in the editor]

Embed it in a page with:

<pre>
{{Diagram|page=BPMN:Example diagram}}
</pre>

which renders as:

{{Diagram|page=BPMN:Example diagram}}

That embed uses this page's one BPMN-or-Gantt slot; a second diagram of either type on the same page would be refused.

[[File:FlexDiagrams BPMN editor.png|thumb|none|700px|The BPMN editor: the shape palette down the left, canvas in the middle, zoom controls on the right.]]

== Gantt ==

Project schedules with tasks, durations and dependencies, drawn with dhtmlxGantt. Useful for planning a long teardown or a multi-stage project on its own page.

'''Example page:''' [[Gantt:Example diagram]] — [{{fullurl:Gantt:Example diagram|action=editdiagram}} open it in the editor]

Embed it in a page with:

<pre>
{{Diagram|page=Gantt:Example diagram}}
</pre>

This help page cannot show that live: it already embeds a BPMN diagram above, and only one BPMN-or-Gantt diagram is allowed per page (see [[#Showing a diagram on another page|above]]). To see it rendered, open [[Gantt:Example diagram]] itself.

[[File:FlexDiagrams Gantt editor.png|thumb|none|700px|The Gantt editor: task grid on the left, timeline on the right, with zoom controls for hours through years.]]

== Tips ==

* Diagrams are ordinary pages: <code>History</code>, <code>Talk</code>, watchlisting and the normal backups all apply.
* Because Mermaid and DOT are text, their page histories produce readable diffs — prefer them over an uploaded image when the diagram is likely to change.
* Give diagrams descriptive names, the same as files — <code>Mermaid:Landis Gyr Focus teardown steps</code> beats <code>Mermaid:Diagram 3</code>.
* The five example pages above are meant to be edited and experimented with. If you want a scratch diagram of your own, make a new page rather than overwriting an example.

== See also ==

* [[Help:Uploading files]] — for photographs, scans and CAD files
* [https://www.mediawiki.org/wiki/Extension:Flex_Diagrams Extension:Flex Diagrams] — the extension providing this

[[Category:Help]]