Repository navigation
Authoring Reference
This is the canonical authoring entry point for people and AI coding tools, including Claude, Codex, Cursor, and Copilot. It defines FlowMotion's YAML keywords and their behavior. Use the complete examples in the authoring cookbook as starting points for complex diagrams.
Compatibility: This reference describes the current development implementation, checked on 2026-11-19. Scene presentation, interactive playback, and the SVG download button are development features; do not assume an older installed release supports them. Match the reference and schemas to the plugin build you use.
- Choose one input format per file. Prefer storyboard YAML for narrated scenes and event YAML for dependency-driven execution.
- Use only the keywords documented for that format. FlowMotion implements a subset of Mermaid and PlantUML, not their complete languages.
- Use stable IDs and reference existing elements. Do not use display labels as references.
- Quote hex colors and text containing YAML punctuation. Write booleans as
trueorfalse, not"true"or"false". - Keep layout, presentation, packet direction, and execution order separate.
- Validate syntax and references, build the model, then inspect playback and the exported SVG. Parsing alone does not prove a diagram looks correct.
- Report unsupported requests rather than inventing fields such as
position,x,y,onClick,next,disabled, oractiveColor.
The tables below enumerate author-facing YAML keys, including accepted-but-ignored compatibility fields. Internal model properties and SVG attributes are not input keywords.
| Format | Identification | Use when |
|---|---|---|
| Storyboard YAML or JSON | Top-level elements and scenes
|
You need nested layout, chapters, scene-specific colors/visibility, parallel messages, or guided presentation |
| Event YAML or JSON | Top-level nodes, optionally flows and events
|
You need graph layout, explicit dependencies, branching, waiting, or process durations |
| File embed | Top-level src plus display options only |
A note reuses a diagram from another file |
| Text DSL | First meaningful line is a supported diagram header | A simple graph or an imported Mermaid/PlantUML-style description is enough |
| draw.io | Recognized draw.io XML or SVG content | You need authored coordinates or an existing drawing |
A .flow extension does not select a grammar: the content does. Do not wrap a standalone .flow file in a Markdown fence. In a note, place its definition inside a flowmotion fence.
Put display options at the top level of YAML definitions, or next to src in a note's embed block. Embed options override file options individually. For a text DSL or draw.io file, use an embed to set these options; do not append YAML to that file.
| Key | Type / values | Default and behavior |
|---|---|---|
src |
File path string | Embed only. Relative to the containing note; / starts at the vault root. The runtime also tries a vault-root fallback for an unresolved relative path |
controls |
Boolean | Hidden unless enabled; shows the expanded playback controls, not the whole toolbar |
interactive |
Boolean |
false. Wait for Next to play one beat or event interval |
controlsPosition |
top, bottom
|
top |
mode |
fit, normal
|
fit; Normal is unavailable inside slides |
height |
Size string using px or vh; number in runtime |
Maximum height. Runtime numbers mean pixels; prefer explicit units for schema compatibility |
width |
Size string using px, vw, or %; number in runtime |
Maximum width, centered. Prefer explicit units |
header |
Boolean |
false. Storyboard scene name and beat counter above the diagram |
footer |
Boolean |
false. Storyboard beat's say caption below the diagram |
paper |
light, dark, none, or color string |
draw.io background sheet. none removes the sheet; Obsidian settings provide defaults |
Size strings accept one to four digits before an optional decimal point and require a unit, for example 70vh, 900px, or 80% where that unit is allowed.
src accepts .flow, .yaml, .yml, .json, .svg, and .drawio at runtime. Prefer .flow, .drawio.flow, and .drawio.svg for plugin integration. An arbitrary SVG is not necessarily a valid draw.io source. Editor schema hints list a narrower set of extensions; the embed parser is authoritative for runtime resolution.
Only the keys in this table may accompany src. Do not add nodes, elements, scenes, animation, or other definition keys to an embed.
```flowmotion
src: ./architecture.flow
interactive: true
controls: true
header: true
footer: true
height: 70vh
```- Interactive storyboards start at time zero. Next plays to the next beat start, or to the timeline end for the last beat.
- All edges listed in one beat travel together. Next does not advance through each packet separately.
- At a beat boundary, the next beat's initial appearance and caption can already be visible. Its motion waits for the next click.
- For event diagrams, Next stops at the next event start/end boundary, including the final playback tail.
- Interactive mode suppresses autoplay, continuous Play/Replay buttons, diagram-click playback, and looping. Expanded controls still allow reset, seek, and event-boundary stepping.
- Reduced motion makes Next jump to the boundary. Ordinary non-interactive playback instead initially shows the finished state.
- SVG ↓ downloads the entire animated timeline, not a still frame or only the current scene. It snapshots Obsidian theme colors into a standalone palette.
- The SVG uses SMIL and repeats independently. It has no Next button and does not preserve interactive pauses, the current slider position, or player speed settings. SVG animation support depends on the viewer.
- There is no
export,gif, orsvgconfiguration keyword. GIF export is not implemented.
| Key | Type / values | Meaning |
|---|---|---|
title |
Text, at most 500 characters | Optional; defaults to storyboard. Also supplies the generated diagram ID/download filename |
speed |
Number, 300-20000 | Default beat duration in milliseconds; default 2200, not a speed multiplier |
elements |
List, at most 300 | Cards, groups, and arrows |
scenes |
Nonempty list | Scenes in playback order; every scene needs at least one beat |
All shared display keys except src can also appear on a storyboard definition.
| Key | Applies to | Meaning |
|---|---|---|
id |
All; required | Unique across the entire elements list. One to 64 characters from A-Z a-z 0-9 _ . > -; prefer letters, numbers, _, and -
|
type |
All; required |
rectangle, cylinder, group, or arrow
|
content |
Cards | List of title/subtitle objects; a title entry is required |
content[].type |
Card content |
title or subtitle
|
content[].text |
Card content | Text, at most 500 characters |
width |
Cards | Number, 0-2000. Overrides natural card width; omit for automatic sizing |
minCardHeight |
Cards | Number, 0-2000. Minimum content-area height; header and padding are added |
label |
Groups/arrows | Mapping: groups use title; arrows use text
|
label.title |
Groups | Visible group heading; omit the label for a layout-only group |
label.text |
Arrows | Static connector label, separate from a packet's data
|
children |
Groups | List of existing card/group IDs; never arrow IDs |
layout |
Groups | Mapping of direction, gap, and align
|
layout.direction |
Groups |
column (default) or row
|
layout.gap |
Groups | Number, 0-400; default 12
|
layout.align |
Groups |
stretch (default), center, or start. Column stretch expands child widths; row layout uses natural widths and top alignment unless centered |
start |
Arrows; required | Mapping containing id
|
start.id |
Arrows | Existing source card/group ID |
end |
Arrows; required | Mapping containing id
|
end.id |
Arrows | Existing target card/group ID |
quiet |
Arrows | Boolean; default false. Faint dashed connector styling |
line |
Arrows |
solid (default), dotted, or thick
|
route |
Compatibility only | Accepted string; currently ignored. Does not select a routing algorithm |
Layout invariants:
- Exactly one non-arrow element must be ungrouped: the layout root.
- Every other card/group belongs to one parent group. Nesting cannot contain cycles.
- Arrows remain outside
children; they do not participate in the root count. - Grouping positions elements; it does not create arrows or execution dependencies.
- Cards reserve room for their largest row set across all beats. Hiding an element does not reclaim its space.
- An unlabeled layout-only group has no visible outline or label to style.
| Key | Scope | Meaning |
|---|---|---|
label |
Scene | Optional name; defaults to scene 1, scene 2, etc. |
caption |
Scene | Accepted string but ignored; use a beat's say instead |
presentation |
Scene | Appearance settings for this entire scene; see the next table |
beats |
Scene | Nonempty list of steps. At most 300 beats across the storyboard |
say |
Beat | Caption text; display requires footer: true
|
ms |
Beat | Number, 200-60000 milliseconds; overrides the document's speed for this beat |
edges |
Beat | One arrow ID, one edge object, or a list of IDs/objects. Omit for a beat without packet travel |
edges[].edge |
Edge object | Required existing arrow ID |
edges[].data |
Edge object | Optional packet label; omitted means an unlabeled moving dot |
edges[].back |
Edge object | Boolean; default false. true moves from the arrow's end to its start |
show |
Beat | Mapping from card IDs to row lists; new rows replace that card's previous row set |
light |
Beat | List of IDs to highlight during this beat. Use card IDs for visible node highlights; group IDs are accepted but do not highlight their children |
Beats play sequentially. Every edge in a beat starts together and travels for min(1200, beatDuration * 0.45) milliseconds. An active connector can remain highlighted for the full beat after its packet arrives.
Rows begin appearing when that beat's packets arrive. With no edges, they start after min(250, beatDuration) milliseconds. The fade-in lasts 250 milliseconds. Rows remain until another show replaces them for the same card; changing scenes alone does not clear them. Use show: {cardId: []} to clear rows at that beat's reveal time.
The last beat is followed by a 1200-millisecond playback tail. This is part of the final interactive interval, not an extra authored beat.
| Key | Structure | Meaning |
|---|---|---|
presentation.defaults |
Mapping | Category-wide defaults for this scene |
presentation.defaults.nodes |
Node settings | All rectangle/cylinder cards |
presentation.defaults.groups |
Group settings | All visible group outlines/labels |
presentation.defaults.arrows |
Arrow settings | All connectors |
presentation.nodes |
Map: card ID to node settings | Per-card overrides |
presentation.groups |
Map: group ID to group settings | Per-group overrides |
presentation.arrows |
Map: arrow ID to arrow settings | Per-arrow overrides |
| Setting | Nodes | Groups | Arrows | Meaning |
|---|---|---|---|---|
visible |
Yes | Yes | Yes | Boolean, default true. false hides the element without changing layout |
opacity |
Yes | Yes | Yes | Number, 0-1; default 1
|
fill |
Yes | Yes | No | Fill color |
stroke |
Yes | Yes | No | Outline color |
color |
No | No | Yes | Connector and arrowhead color |
highlight |
Yes | No | Yes | Boolean, default true. Allows automatic beat/packet highlighting; true alone does not activate an idle element |
arrowheads |
No | No | Yes |
start, end, both, none; default is the original arrow's end head |
packet |
No | No | Yes | Boolean, default true. Show packet motion independently from the connector |
Precedence is: original appearance, this scene's category defaults, then its per-ID overrides. Explicit scene colors take priority over state colors; a highlight may still change outline width.
Presentation resets at every scene; it is not inherited from the preceding scene. Repeat any settings you still need.
Visibility is not transitive:
- Hiding a node hides its content rows, but not connected arrows.
- Hiding a group hides its outline and heading, not its children.
- Hiding an arrow hides its connector, labels, and arrowheads, but not its packet. Set
packet: falseto hide the packet. -
arrowheadschanges the decoration, not travel direction. Useback: truefor a response packet. - There is no
disabledstate. Use opacity andhighlight: falseto de-emphasize an element.
Scene presentation applies for a whole scene, not per beat. Split a sequence into scenes when connector visibility or emphasis must change after a request.
show.<cardId> is a list of at most 20 row objects.
| Key | Values | Meaning |
|---|---|---|
type |
row (default), graph
|
Row renderer |
tone |
gray (default), blue, purple, green, orange
|
Accent color |
tag |
Text | Small left label |
text |
Text | Main row text |
meta |
Text | Secondary text |
mark |
Text | Right-hand marker |
mono |
Boolean | Monospace row text; default false
|
nodes |
List of at most 12 names | Graph row only: graph node names |
links |
List of two-name lists | Graph row only: edges such as [input, output]
|
lit |
List of graph node names | Graph row only: highlighted graph nodes, not diagram card IDs |
Use the text fields for type: row, and nodes, links, and lit for type: graph. Titles, captions, labels, and ordinary row text fields are limited to 500 characters.
| Key | Type / values | Meaning |
|---|---|---|
diagram |
Mapping | Optional graph-wide settings |
diagram.id |
ID | Defaults to diagram; affects generated SVG IDs and filename |
diagram.direction |
LR, RL, TB, BT
|
Layout direction; default LR
|
diagram.edgeLabels |
Boolean | Default false. Show flow payloads as static connector labels |
groups |
List, schema maximum 200 | Optional nesting definitions |
nodes |
Nonempty list, at most 200 | Graph nodes |
flows |
List, at most 400 | Connectors |
events |
List, at most 1000 | Optional explicit animation script |
animation |
Mapping | Playback settings below |
animation.autoplay |
Boolean | Default true; plugin settings, reduced motion, and interactive mode can prevent autoplay |
animation.loop |
Boolean | Default true; interactive progression stops instead |
animation.speed |
Number, 0.1-10 | Playback multiplier; default 1, unlike storyboard speed
|
Shared display options also apply. IDs contain one to 64 characters from A-Z a-z 0-9 _ . -. Prefer IDs that start with a letter. Labels and other ordinary text fields are limited to 120 characters.
| Key | Scope | Meaning |
|---|---|---|
id |
Group/node/flow; required | Unique within its category; a node and group cannot share an ID |
label |
Group/node | Display text; node default is its ID, group label is optional |
parent |
Group | Existing enclosing group ID; no nesting cycles |
shape |
Node | Default rect; see all values below |
group |
Node | Existing containing group ID |
lines |
Node | Detail text under the title; schema allows at most 60 lines |
style |
Node/flow | Mapping of static style properties below |
from |
Flow; required | Existing source node ID, not a group |
to |
Flow; required | Existing target node ID, not a group |
payload |
Flow | Default packet text; also a static label if diagram.edgeLabels: true
|
line |
Flow |
solid (default), dotted, thick
|
head |
Flow | Target decoration; default arrow
|
tail |
Flow | Source decoration; default none
|
headLabel |
Flow | Target-end label; use at most 20 characters for schema compatibility |
tailLabel |
Flow | Source-end label; use at most 20 characters |
curve |
Flow | Boolean, default false. Request a curved connector |
All shape values: rect, round, stadium, diamond, circle, cylinder, hexagon, subroutine, parallelogram, start, end, bar, class.
All head/tail values: none, arrow, circle, cross, triangle, diamond, diamond-filled.
| Style key | Type | Behavior |
|---|---|---|
style.fill |
Color string | Node fill in idle state |
style.stroke |
Color string | Node outline in idle state; connector color on flows |
style.color |
Color string | Node label/detail text |
style.strokeWidth |
Number, 0-12 | Node outline width in idle state or flow line width |
The schema accepts the same style object on nodes and flows, but flows use stroke and strokeWidth, not fill or color. Active node states can override idle styles. Use storyboards when scene-specific appearance is required.
| Key | Type / values | Meaning |
|---|---|---|
id |
ID; required | Unique event ID |
type |
Event type; required | One of the types in the following table |
flow |
Flow ID | Required for transfer
|
node |
Node ID | Required for process, emit, complete; use on wait for a visible waiting state |
payload |
Text | Packet label override |
after |
Event ID or list | Dependencies that must finish before this event starts |
until |
Event ID or list |
wait: wait for these events to finish; also establishes ordering dependencies |
select |
Event ID or list |
branch: direct child events to take; must be nonempty |
duration |
Number, 0-60000 | Milliseconds; defaults depend on type |
fail |
Boolean, default false
|
A finished process leaves its node in an error state |
| Event type | Default duration | Scheduling and visual effect |
|---|---|---|
transfer |
1500 ms | Moving packet along flow
|
process |
1200 ms | Node processing state and progress bar |
emit |
600 ms | Node activity and progress bar |
complete |
0 ms | Marks a node completed |
wait |
0 ms | Waits until all until targets finish; explicit duration is also a minimum interval from its start |
fork |
0 ms | Dependency marker; child events sharing it in after can run concurrently |
join |
0 ms | Starts after its live predecessors finish; skipped only if all after paths are skipped |
branch |
0 ms | Selects listed direct child events; choice is authored, not calculated from live data |
Events with no after can start at zero. File order does not serialize them. An ordinary event is skipped if an after dependency is skipped or excluded by a branch. A join can continue from the remaining live paths.
Every selected branch child must include the branch ID in its own after. All referenced events must exist. after/until dependencies must be acyclic. A reverse message needs a separate reverse flow; back is a storyboard edge keyword, not an event keyword.
If events is omitted or empty, FlowMotion derives node processes and flow transfers from the graph. Incoming packets precede node processing; outgoing packets follow it. Back edges are drawn but not scheduled. To control repetition, author separate uniquely identified events; there is no event type loop.
The event timeline has an 800-millisecond final tail. Parallel event examples are in the cookbook.
Use valid CSS color names, quoted hex colors such as '#2563eb', or numeric rgb()/rgba()/hsl()/hsla() strings accepted by the parser. Prefer hex or RGB for portability. Do not use arbitrary CSS, url(...), var(...), or expressions as input colors. tone is an enum, not a CSS color.
Scene settings do not expose arbitrary CSS, animation code, or event handlers. Do not insert HTML/scripts into labels. Mermaid-style link callbacks are not an execution API.
For complex diagrams, use the complete YAML references above. These links describe the text DSL's implemented subset:
| Surface | Authoring reference |
|---|---|
| Headers and supported diagram families | Diagram types |
Flowchart shapes, line operators, arrow labels, chained arrows, &, groups |
Writing diagrams |
classDef, class, :::, style, linkStyle, click
|
Writing diagrams |
| Sequence participants/messages and unsupported control-block behavior | Diagram types |
| Activity, state/class, Gantt, mind map, architecture, and C4 entry points | Diagram types |
The FlowMotion-specific text directives are:
| Directive | Meaning |
|---|---|
%% @duration <nodeId> <ms> |
Node process duration, 0-60000 ms |
%% @fail <nodeId> |
Leave that node's process in an error state |
%% @speed <multiplier> |
Playback multiplier, 0.1-10 |
%% @loop off |
Do not loop; on enables looping |
%% @autoplay off |
Do not autoplay; on enables autoplay |
Known compatibility-only constructs are not promises of behavior: sequence alt, loop, par, activation, and notes do not implement execution branching or parallel control blocks. Gantt compatibility settings listed on Diagram types are ignored. Storyboard caption and route are ignored too.
Use event branch/fork/join or simultaneous storyboard edges for real authored execution. For draw.io, use the drawing format and a display-only embed; there is no documented YAML-to-draw.io execution override.
This page is the human/AI authoring contract, not a replacement for validation. The matching checkout's runtime parsers decide what runs. Its schemas describe supported keys, enums, completion, and stricter editor checks; timeline and rendering code define behavior.
| Evidence | Source in the main repository |
|---|---|
| Generated event schema | schema/diagram.schema.json |
| Generated storyboard schema | schema/storyboard.schema.json |
| Schema definitions and shared display keys |
src/schema/diagram.ts, src/schema/story.ts, src/schema/common.ts
|
| Runtime YAML parsing and references |
src/core/parse.ts, src/story/parse.ts
|
| Embed resolution and display parsing |
src/core/embed.ts, src/core/view.ts
|
| Scheduling and automatic graph animation |
src/core/timeline.ts, src/story/timeline.ts, src/core/auto.ts
|
| Visibility, highlighting, rows, and packet positions |
src/render/frame.ts, src/render/presentation.ts
|
| Text syntax subset |
src/text/parse.ts, src/text/kinds.ts
|
| Export and interactive playback |
src/render/svg.ts, src/export/html.ts, src/runtime/player.ts, src/runtime/mount.ts
|
Source paths are relative to the repository checkout, not the vault. Consult those files from the same revision as the installed plugin. Unknown fields can be ignored by some runtime parsers, so a rendered preview is not evidence that an invented key works.
Use lintSource from src/schema/index.ts for schema and reference diagnostics. Use buildModel from src/model.ts to check layout and scheduling. A src block must be parsed with parseEmbed and its file resolved in the vault; it is not a standalone diagram for buildModel.
See the cookbook validation procedure for a runnable example. External JSON Schema alone cannot prove ID references, acyclic dependencies, valid nesting, or correct animation.
When adding or changing an author-facing keyword, update its parser, schema, generated JSON schemas, this reference, and the related cookbook or topic page together. Validate the complete examples against the same checkout. Do not document an accepted-but-ignored field as implemented behavior.
© 2026 @vrsarin. FlowMotion documentation.