The editor
Last updated: 17 November 2026
Diagon's window is a text editor on the left and a live diagram on the right. This page covers what happens between the two: how the preview keeps up, how the layout engine decides where things go, what dragging does to your code, and how exports come out.
If you haven't written a diagram yet, start with Getting started. The language is the syntax reference.
The window
The toolbar is one row of buttons with icons. Left to right: New, Open and Save; Export, which opens a menu; Fit and Auto-arrange; the Direction and Routing dropdowns; Auto-color; and at the right end a moon (or sun) button for the theme and Connect AI. In a narrow window some buttons show only their icon — rest the mouse on one to see its name. Connect AI opens the dialog for connecting an AI assistant you already use — see AI assistants. The dot on that button is grey while the connection is off, amber while Diagon waits for an assistant, and green once one is connected.
The status bar runs along the bottom of the window. Its left end reads N nodes · M edges · Xms after each render, or N issue(s) when something didn't parse. Its right end shows the line and column of the text cursor, like Ln 3, Col 9, and how far the picture is zoomed.
The code pane has a line-number gutter that scrolls with the text and a red error bar underneath that appears only when there's something to say. A faint band marks the line the text cursor is on, and the number of a line with a mistake turns red — in a diagram with boxes too. Pressing Tab in the code pane inserts two spaces rather than moving focus. The font is Cascadia Mono where it is installed.
The preview shows the diagram, with zoom buttons in its bottom right corner. While the diagram is empty it shows a card that says Nothing to draw yet, with a line to try. The name of the open file sits above the code pane; it reads untitled.diag until you save.
The divider between the panes is draggable.
Live preview
Typing re-parses and re-renders after a short pause — about a seventh of a second — so the diagram follows you without redrawing on every keystroke.
When a line doesn't parse, the error bar names the line and the reason, and the preview keeps showing the last diagram that worked. You're never left staring at a blank canvas because of a typo halfway down.
The suggestion list
A list of suggestions pops up as you type: the language's own words first — shape:, direction:, shape names and so on — then the ids you have declared, including nested paths like company.aks.pod1. Only what is valid in that spot is offered. Type shape: and every shape appears on its own, the default first; the same goes for direction: and routing:. Inside an edge's braces the list offers stroke: and style:, and after style: the line styles.
- ↑ and ↓ choose, Enter or Tab accepts, and Ctrl+Space opens the list on demand.
- Esc dismisses the list. After that, Enter is an ordinary new line again.
- Type
{and the list offers}straight away. Accept it and you get an indented block with the closing brace on its own line below, and the cursor waiting inside. - If a suggestion ever lands when you did not want it, Ctrl+Z puts back exactly what you typed.
Since 1.5.0 the list opens above the line when there is no room under it, and it stays inside the editor.
The layout engine
Diagon places every node itself. There are no third-party layout libraries in it.
Flat diagrams go through a layered pipeline: cycles are broken, nodes are assigned to ranks, the order within each rank is shuffled to reduce crossings, and then each rank is placed sideways so that a parent sits centred over its children and a chain stays straight. Ranks sit about one box-height apart; a gap only grows where an edge label or a wide fan-out needs the room. Larger diagrams get fewer refinement passes so they still render quickly.
Diagrams with containers are laid out container by container, innermost first, and then cross-container edges are straightened where that doesn't cost anything. Children with no edges between them are packed into a few rows shaped for the flow; when a box holds a flow plus unconnected children, the unconnected ones form a block beside it.
You don't configure any of this. What you control is direction, routing, and pinning individual nodes.
Edge routing
routing: curved (the default) draws smooth splines, orthogonal draws right angles with rounded corners, and straight draws direct lines.
Orthogonal edges are routed around nodes rather than through them — in flat diagrams as well as in diagrams with boxes (since 1.4.0) — using a visibility graph and a shortest-path search; arrows leave a node by the face that faces the flow and lines run down the middle of a gap. In diagrams with boxes a curved edge that has to go around something follows the same route with large rounded corners, and a clear one stays a straight line. Where several edges converge on the same node they're given separate landing points on its face, so arrowheads don't pile up on one spot. Edge labels are nudged apart from each other and pushed off any node they'd otherwise sit on top of.
Two limits are worth knowing on very large diagrams:
- Above 600 edges, edge labels are hidden. The lines stay.
- Routing gets a 1.5 second budget per layout. Edges that don't get routed in time fall back to direct lines, which may cross a node.
Zoom and pan
- Scroll zooms, centred on the cursor, between 0.04× and 4×.
- The − and + buttons in the bottom right corner of the preview zoom as well. The percentage between them says how far you are zoomed, and so does the right end of the status bar. Click the percentage to go back to 100%.
- Drag the background pans.
- Ctrl+0, the Fit button in the toolbar, or the last button in that corner frames the whole diagram with a margin, never magnifying past 1.6×.
Zoom and pan are a view transform. They never re-run the layout, so nothing shifts underneath you.
Dragging a node
Drag any node and it moves. What happens next depends on the kind of diagram, and the difference matters.
In a flat diagram, letting go writes the position into your code. Diagon rewrites that node's line with x: and y: inside its attribute block, keeping any attributes already there:
diagon
api: API
db: Database
api -> dbDrag db and the line becomes:
diagon
api: API
db: Database { x: 320, y: 40 }
api -> dbIf the node has no line of its own — it only ever appeared in an edge — Diagon appends one:
diagon
api -> db
db { x: 320, y: 40 }That's the round trip: the diagram and the code stay the same thing. Since 1.5.0 the rewrite is one undo step, so Ctrl+Z takes the move back.
In a diagram with containers, dragging still moves the node, but the position is held in memory only. It isn't written to your file and it's gone when you close the app. Positions in boxed diagrams come from the container layout, so there's nowhere in the text for a coordinate to live — and nothing for Ctrl+Z to bring back.
A pinned node shows a small purple dot at its top-right corner and stays where you put it while everything else lays out around it. Its edges take the shortest clear path to it: a straight line when nothing is in the way, and a detour around whatever is.
Dragging a container's title bar moves the whole group, children included. That pin is in memory too.
Resizing
In diagrams with boxes, every root-level node and box has a small triangular grip at its bottom-right. Dragging it makes that item bigger.
Manual sizes are grow-only — you can't shrink something below the size its contents need — and they live in memory for the session, like boxed-diagram pins: nothing is written to your file, and they're gone when you close the app.
Exports keep them. Only the little grip itself is removed on the way out; the geometry an export is cut from is the resized geometry, so an SVG, PNG or GIF comes out at the sizes you dragged to. If you want the engine's own sizes back, Auto-arrange first and then export.
Auto-arrange
Ctrl+L, or the Auto-arrange button, hands every node back to the layout engine.
In a flat diagram it strips every x: and y: from your code and lets the engine place everything again. In a boxed diagram it clears the in-memory pins and manual sizes.
Reach for it when you want all the pins gone at once. To take back a single move, use Ctrl+Z.
Undo
Up to 1.4.0 Diagon had no undo for its own actions: a drag write-back, Auto-arrange or a toolbar dropdown replaced the text in the code pane and cleared its undo history. Since 1.5.0 Ctrl+Z takes those back too. There is still no Edit menu, so the key is the only way to undo.
- What Diagon writes into your code. A moved node, a choice of Direction or Routing in the toolbar, and Auto-arrange each go in as one undo step, like anything you type. Ctrl+Z takes the step back, and goes on from there through what you typed before. In a diagram with containers Diagon does not write these into your code, and Ctrl+Z does not bring them back. Only a very large rewrite is different: when the first line Auto-arrange changes and the last are more than 400 lines apart — as a rule the first node you placed and the last — it is not an undo step, and the undo history starts anew there.
- New and Help → Examples. Both replace the diagram on screen, and Ctrl+Z brings your previous text back. If that text had unsaved changes, a notice at the bottom left says that Ctrl+Z brings it back. Either way the diagram is untitled now, and Save asks where to put it.
- Open. Ctrl+Z cannot go back past opening a file: after Open the undo history starts anew.
- An assistant's change. A change made by a connected AI assistant goes in the way a paste would, so one Ctrl+Z takes the whole change back.
- While a dialog is open. Ctrl+Z leaves the diagram alone. The step is still there when you close the dialog.
There's still no prompt about unsaved changes when you press New, Open, or quit. New can be undone; before you open another file or quit, save first.
Direction and routing controls
The toolbar dropdowns do slightly different things depending on the diagram.
In a flat diagram they write the directive into your code, exactly as if you'd typed direction: right at the top — and Ctrl+Z takes it back. In a boxed diagram they change the view without touching your file.
Theme
The moon (or sun) button at the right end of the toolbar switches the canvas and what exports look like between dark and light — background and palette both. Your choice is remembered between sessions.
Auto-colour
Auto-color gives each group in a diagram with containers its own colour from a fixed palette, and tints each edge to match the deeper of the two groups it connects. It only applies to grouped diagrams.
The Groups dropdown next to it decides how coarsely to group: innermost (the default) colours each leaf-most container separately, while depth 0 gives every top-level group one colour, so a whole cluster shares a hue. Both the toggle and the depth are remembered between sessions.
Files
Open (Ctrl+O) reads .diag and .txt.
Save (Ctrl+S) and Save As (Ctrl+Shift+S) write plain UTF-8 text, defaulting to diagram.diag. There's no project format and no database — a diagram is one text file.
Help → Examples opens one of four diagrams that come with Diagon: Login flow, System architecture, Brand icons and Arrow styles. An example opens as a new, untitled diagram and replaces the diagram on screen. Ctrl+Z brings your previous text back, and Save asks where to put the diagram.
Export
Export in the toolbar opens a menu with three entries, SVG, PNG and GIF (the GIF since 1.6.0). The File menu has the same three, as Export SVG…, Export PNG… and Export GIF…. None has a keyboard shortcut.
SVG produces a standalone file: the styling is embedded, remote icons are converted to inline data, the drawing is cropped tight with a 40-pixel margin, and a background rectangle is included so it looks right wherever you drop it. It is the one export that stays sharp however far you zoom in. The dashes of a flow line keep moving in it wherever a web browser draws the file: in a browser tab, and on a Confluence page, both on the page and when you click the picture to see it in full (tested on Confluence Cloud in November 2026). In slides, a text document or an e-mail an SVG stands still, where it is shown at all.
PNG rasterises the same thing at 2× onto the current theme's background. In a PNG the dashes of a flow line stand still.
GIF is the same picture at 2× in which the dashes of flow lines keep moving. It is for the places where an SVG stands still or is not accepted: slides, chat, e-mail. One round of the dashes takes 0.72 seconds; the file holds it as 18 pictures of 40 milliseconds each and repeats them for ever, without a jump. From one picture to the next only the dashes are stored again, so the file stays small: the Arrow styles example makes one of about 26 KB.
A few things to know about the GIF:
- A GIF holds 256 colours at most. That is plenty for a diagram: large even areas keep their exact colour, and the soft edges of letters and lines come out very close to theirs.
- It is made of pixels, so zoomed in far it gets soft. A very large diagram is saved smaller than 2×, so that a picture has 16 megapixels at most.
- A diagram without
flowlines makes a GIF of one picture, and the status bar says that nothing moves in it. - The GIF moves whatever your computer says about showing less motion, and also in a diagram so large that the dashes stand still in the window.
Which one for a diagram that moves? On a Confluence page, the SVG: it moves there, it is the sharpest and it is the smallest file. Wherever a web browser does not draw the picture, the GIF.
Icons in exports
Icons are fetched fresh at export time, through the app's own network stack — which means it honours your system proxy and certificate store, so it works behind a corporate proxy the way a browser does. Each icon gets 10 seconds and a 6 MB ceiling; an icon that fails is left out rather than blocking the export. So is a picture an AI assistant added that is still waiting for your answer, or is not loaded.
One case produces a visible message: if a remote icon host serves no CORS headers, the browser engine refuses to hand over the pixels of the canvas, and PNG export and GIF export are blocked. The error bar tells you so and suggests exporting an SVG instead, which is unaffected (and whose arrows move as well), or a CORS-friendly icon host.
Keyboard shortcuts
| Shortcut | Action |
|---|---|
| Ctrl/Cmd+N | New |
| Ctrl/Cmd+O | Open… |
| Ctrl/Cmd+S | Save |
| Ctrl/Cmd+Shift+S | Save As… |
| Ctrl/Cmd+0 | Fit to screen |
| Ctrl/Cmd+L | Auto-arrange, clearing pins |
| Ctrl+Z | Undo — see Undo above |
| Ctrl+Space | Open the suggestion list |
| Tab, in the code pane | Insert two spaces, or accept a suggestion while the list is open |
Export, Connect AI, the theme, Auto-color and the licence panel are toolbar or menu only. Help → Syntax cheatsheet shows a short reminder of the grammar without leaving the app, and Help → Examples opens the four example diagrams.
Performance notes
The layout engine trades refinement for speed as diagrams grow: it does its most thorough ordering work up to about 400 nodes, fewer passes up to 1,500, and skips the most expensive step above that. Diagon's own test suite lays out an 80-node, 65-edge architecture diagram on every run.
Past about 1,200 nodes the canvas switches to a lighter drawing mode, and past 600 edges the edge labels are hidden — both to keep the preview responsive while you type. In the lighter mode the dashes of flow lines stand still, as they do in a diagram with more than 200 flow lines. If you're near those numbers, routing: straight skips the pathfinding entirely and is noticeably faster.