NeuralFlow — complete guide

NeuralFlow is the diagram language built into the MD Dashboard engine. You write a fenced ```neuralflow block in any Markdown file the engine serves, and it renders as an SVG diagram — labels in SF Pro Display, all $…$ math in KaTeX.

It draws three families well: - Structure charts — network / architecture / status topologies (groups, status colours, routed links). - Flow diagrams — neural nets and pipelines with math in the nodes. - Flowcharts / decision charts — one flowchart line and the whole layout (sizes, lanes, elbows, yes/no colours) is derived; see §6.

Everything below is live: each example is a real block, so open this file in the dashboard to see it rendered.

1. Anatomy of a block

<div class="neuralflow" data-neuralflow-source="direction LR              ← diagram options (optional; sensible defaults)&#10;node A [Hello | world]    ← nodes&#10;node B [Next]&#10;A --&gt; B : link label      ← edges"></div>

• One statement per line. Blank lines are ignored.
• A line starting with # is a comment.
• Order is free: you can declare edges before or after nodes; every node an edge references must exist somewhere in the block.

2. Nodes

node ID [Title | Detail] OPTION=VALUE OPTION=VALUE …

• ID — starts with a letter; then letters, digits, _, -. Used only to reference the node in edges; never shown.
• [Title | Detail] — the label. The part after | is optional and renders lighter/smaller under the title. Either part may contain math and line breaks.
• Math — anything between dollar signs renders with KaTeX: node R [ReLU | $a=\operatorname{ReLU}(z)$].
• Multi-line — a literal \n starts a new line inside a part: node C [campus-core01 \n 10.0.108.170 \n ✅ N2 ESTAB].

Node options

3. Edges

FROM --> TO                       solid link (present / working)
FROM ..> TO                       dotted link (missing / logical / not-established)
FROM --> TO : label               with a label
FROM --> TO {options} : label     with colour and/or label position

• One edge per line. Chains like A --> B --> C are not supported — write A --> B and B --> C.
• Labels render with KaTeX too: A --> B : $z$.

The { … } options (after the target)

Combine them: A --> B {blue at=0.25} : N2 SCTP 38412.

Tip: labels are auto-nudged apart if they'd collide with each other or a node, so at= is a strong hint rather than an absolute pin.

4. Groups (containers)

group ID "Title" [fill=… stroke=…]
  node A [ … ]
  node B [ … ]
end

• Draws a rounded container with a title. Default colour is the amber theme box; override with fill= / stroke=.
• Nestable — put a group … end inside another.
• Every group needs a matching end (unclosed = a syntax error).
• The box is drawn around wherever its members land, so it always wraps them.

5. Diagram options

Put these on their own line, anywhere in the block.

6. Flowchart mode

A decision chart wants different things from a neural net: every box the same size, a dead-straight main path, branches that peel off downwards, and labelled yes/no lines. Building that by hand means size W H, a level= on every node, invisible spacer nodes to stop single-node columns floating to the middle, and push= to buy room for a label. flowchart derives all of it. Write the logic; the drawing is the renderer's problem.

That is the whole source — no size, no level=, no spacers, no colours.

What it derives

Options

flowchart takes optional key=value settings on the same line:

Everything else still applies

direction TB, status=, fill=/stroke=, $…$ math, \n line breaks, groups, and explicit {colour} on a link all work as usual and override what the mode derived. So do gap (lane spacing), layergap (column spacing) and level= — set one and that part stops being automatic. edges curved (or straight/ortho) opts back out of the flow router entirely.

Feedback loops still don't route. The layout is layered — a node's column is its distance from a source — so a back edge (RETRAIN --> TRAIN) makes that ill-defined and tangles the chart. Put the return in the node's text (Bigger network \n → retrain) or end with a ↺ back to … node, and describe the cycle in the caption.

7. Colours

Anywhere a colour is accepted ({…} on links, fill=/stroke= on nodes and groups) you can use:

• Palette shorthands: blue green red amber orange purple teal pink gray slate
• Any CSS colour: a name (tomato, rebeccapurple), #hex, rgb(…), hsl(…).

No spaces inside a fill=/stroke= value (a space ends the option): write rgb(16,185,129), not rgb(16, 185, 129). Inside a link's {…}, spaces are OK.

Status vs custom: status= is the quick semantic set (6 presets, includes the right background, border, and text colour). fill/stroke are for anything else and override status.

8. Sizing

Nodes auto-size to their content by default. Override per node:

• Set w or h alone — the other stays auto.
• size W H (diagram option) makes all nodes uniform; per-node w/h still win.

9. How layout & routing work

Understanding this helps you get clean diagrams.

• Layered. A node's column (LR) / row (TB) is its distance from a source along the arrows. It's automatic — you don't place nodes by pixel.
• Lanes (with groups). Each top-level group gets its own cross-axis band, so group boxes never overlap. Order within a lane follows declaration order.
• Lanes (flowchart mode). A node's first outgoing link keeps its lane, later ones peel off into the next free one — see §6. Otherwise a column's nodes are stacked and the stack is centred, which is why a one-node column floats to the middle unless you pad it.
• Ports. When several links share a node face, their attach points fan out (ordered by where the other end sits) so lines separate at the node. Diamonds attach on their slanted edges; boxes near the middle.
• Orthogonal routing (default for structure charts). Links are right-angle elbows with small rounded corners. The turn sits in the gap before the target, so a multi-column link never crosses an intermediate node.
• Channel offset. Parallel links in the same column-pair are nudged apart so they read as distinct lines.
• Label de-overlap. After placement, labels that collide with each other or with a node are pushed apart.

Levers when a chart is busy

1. edges curved / edges straight — change connector style.
2. layergap (longer links / more room) and gap (more vertical space).
3. Colour links by plane/family with {colour}.
4. at= on a link (or labelat) to reposition labels.
5. level=N on a node to pin its column.
6. w=/h= to size specific nodes.

10. Fonts & math

• Text is SF Pro Display (falls back to the system UI font off Apple).
• Math is KaTeX — put $ … $ in any title, detail, or edge label. Math scales with the surrounding text automatically.

11. Recipes

Fault state (dotted links, coloured by plane)

Troubleshooting tree (diamonds)

More full recipes (site topology, healthy, interface map) live in neuralflow-showcase.md.

12. Cheat sheet

BLOCK        ```neuralflow …  ```
DIRECTION    direction LR | direction TB
FLOWCHART    flowchart [fit=auto|off|NN] [shapes=auto|manual] [colors=auto|off]
             (decision charts: uniform sizes, branch lanes, elbows, yes/no colours)
CONNECTORS   edges ortho | curved | straight        (ortho = default for structure)
SPACING      gap 20 (within a column)    layergap 150 (line length between columns)
GROUP        group ID "Title" [fill=… stroke=…]  …  end     (nestable)
NODE         node ID [Title | Detail]              (math: $ … $  → KaTeX)
  status     status=ok | warn | err | crit | off | info
  shape      shape=box | diamond | circle
  colour     fill=…  stroke=…   (name · #hex · rgb() · hsl())
  size       w=NN  h=NN          (px; auto by default)
  pin        level=N
MULTILINE    [line1 \n line2]
LINK         A --> B  (present)      A ..> B  (missing / logical)      (one per line)
LINK OPTS    A --> B {colour at=0.3} : proto port
LABEL POS    per-edge {at=0…3} ; diagram-wide `labelat 0…1`
COMMENT      # …

13. Gotchas & troubleshooting

• Syntax error box ("unknown command …") appears in place of the diagram and names the line. Most common causes:
• Chained edges — A --> B --> C. Split into one edge per line.
• Group title missing quotes — use group cu01 "cu01 10.0.108.150".
• Unclosed group — every group needs an end.
• & is fine in labels/titles (no escaping needed).
• \n is a literal backslash-n (each statement is one line), not a real newline.
• Spaces in rgb()/hsl() for fill=/stroke= break the option — use no spaces, or use #hex.
• Keep the ```neuralflow fence flush-left — a 4-space indent turns it into a Markdown code block.
• A diagram is "structure" (dark ortho look) when it has any group, status=, dotted ..>, or coloured link; otherwise it keeps the plain neural look. flowchart always uses it.
• A flowchart step turned into a diamond — its label ends in ?, or both its exits are labelled yes/no. Add shape=box to that node, or shapes=manual to the flowchart line.
• A flowchart came out small — fit=auto scaled it to the content column. Shorten the labels or drop a column; or set fit=off and accept the scrollbar.