Skip to content

Diagrams

Audience: authors.

LQMS has two ways to put a diagram in a document: the draw.io editor for drawn diagrams (flowcharts, process maps, org charts, anything shape-based) and Mermaid code blocks for text-first / UML diagrams. Both freeze with the version and appear in the reading view and the PDF.

1. Drawing a diagram (draw.io)

In the draft editor, type / and choose Diagram, or use the insert menu. This opens a full-frame draw.io editor: the canvas takes the whole screen, with one slim top bar — Back, the title, a caption/alt toggle, and Save. Draw your diagram, then Save to drop it into the document and return to the editor.

  • The diagram appears inline in the reading/content surface at the point where you inserted it.
  • To edit it later, double-click the diagram — it re-opens in the draw.io editor with all your shapes intact.
  • The editor is fully self-hosted: it never calls out to the internet. Nothing you draw leaves the system, and there is no online account or template gallery — this is deliberate (a controlled QMS must not leak content to third-party services).
  • Add an alt text / caption via the toggle in the top bar for accessibility and for the PDF.

The Diagram command is disabled on the create form (before the document exists) with a hint to save the draft first — a diagram needs a version to attach to.

2. Editing imported diagrams

Diagrams brought in from the previous QMS (draw.io originals) arrive as editable diagram nodes, not flat pictures. Open one the same way — double-click — and you get the real shapes in the draw.io editor, ready to change.

First-save note. An imported diagram initially carries its original preview image alongside the source. The first time you save an edit, LQMS upgrades it to the standard self-contained diagram format and drops the preview. From then on it behaves exactly like a diagram you drew in LQMS. This is a one-time, automatic step — you do not have to do anything.

3. Mermaid diagrams (UML and text-first)

For diagrams you would rather express as text — sequence diagrams, class diagrams, state charts, quick flow sketches — use a Mermaid code block (the Mermaid item in the slash menu, or a fenced ```mermaid block in source mode). You write the diagram in Mermaid syntax and it renders in the reading view.

Use Mermaid when the diagram is naturally text (and diff-friendly, and easy for an assistant to generate); use the draw.io editor when you want to draw and position shapes freely.

In the PDF export, draw.io diagrams render as images. Mermaid diagrams cannot render without a browser, so in a PDF they appear as a labelled "Mermaid diagram — source" block showing the diagram's source text rather than the rendered picture. Keep this in mind for documents whose controlled copy is the PDF.