README file from
GithubFlowMotion
Turn any system into a diagram that moves.
FlowMotion draws architecture, process, and data-flow diagrams that come alive. Watch requests travel through your services, see where work waits, and spot the bottleneck at a glance.
- Works in your notes. Add a diagram to any Obsidian note.
- Simple to write. Use the familiar Mermaid or PlantUML style.
- Animated. Each arrow carries a packet. Each step takes time. Each node waits for its inputs.
- Offline. No account, no cloud, no internet connection needed.
- Light and dark. Diagrams match your theme.
See it in action
```flowmotion
flowchart TB
user((User)) -->|request| gw{Gateway}
subgraph platform [Platform]
gw -->|ok| api[API Service]
api --> db[(Orders DB)]
end
%% @duration db 700
```
Paste this into a note, switch to reading view, and press play.
Get started in 5 minutes
You need two things: Node.js (the LTS version) and Obsidian.
1. Download FlowMotion. On the GitHub page, click Code → Download ZIP. Unzip the file.
2. Open a terminal in the FlowMotion folder.
- Mac: open Terminal, type
cdfollowed by a space, drag the FlowMotion folder into the window, and press Enter. - Windows: open the FlowMotion folder in File Explorer, click the address bar, type
cmd, and press Enter.
3. Build FlowMotion. Type these two commands, pressing Enter after each:
npm install
npm run build
4. Install it in your Obsidian vault. Replace the path with the folder that contains your notes (your vault):
npm run install-plugin -- "/path/to/your/vault"
5. Turn it on in Obsidian.
- Open Settings → Community plugins.
- Turn off Restricted mode if it is on.
- Enable FlowMotion.
That's it. Create a note and paste a diagram from the example above.
Your first diagram
- Open a note.
- Right-click in the note and choose Add FlowMotion diagram.
- Choose Inline diagram.
- Edit the text. The preview updates as you type.
To edit a diagram with help (autocomplete, error checks, and a live preview), hover over it and click ✎ Edit.
Select SVG ↓ on a diagram to download an animated SVG. To play one storyboard beat at a time, add interactive: true to its definition or src: block, then select Next for each beat.
What you can draw
| Diagram | Use it for |
|---|---|
| Flowchart | Systems, processes, decisions |
| Sequence | Who talks to whom, and in what order |
| Activity | Step-by-step business workflows |
| State | Things that move between states |
| Mind map | Ideas and plans |
| Gantt | Project timelines |
| C4 and architecture | Software and cloud landscapes |
| Class and ER | Data models |
Full syntax: Writing diagrams.
Authoring reference for people and AI tools
Use the authoring reference as the canonical keyword guide. It covers both YAML formats, display options, defaults, limits, scene behavior, and unsupported constructs. The cookbook provides complete complex examples, validation commands, and a reusable authoring prompt for Claude, Codex, Cursor, Copilot, or another coding tool.
Match the reference and schemas to your plugin build. The reference identifies development features that older installed releases may not support.
Storyboard scene presentation
Set presentation on a scene to change how its elements look. The scene presentation example shows the syntax. Use defaults for all nodes, groups, or arrows, and use the corresponding maps to override individual element IDs. Each scene starts with the original appearance; settings do not carry over.
| Elements | Options |
|---|---|
| Nodes | visible, opacity (0–1), fill, stroke, highlight |
| Groups | visible, opacity, fill, stroke |
| Arrows | visible, opacity, color, arrowheads (start, end, both, none), packet, highlight |
Colors accept a CSS color name, a 3-, 4-, 6-, or 8-digit hex value, or a valid rgb()/rgba()/hsl()/hsla() value. Functional colors support comma-separated channels or space-separated channels with optional / alpha. Use transparent for a transparent color or none for no fill or stroke. Invalid colors produce a configuration error. Scene colors take precedence over highlight colors. Set highlight: false to suppress node or arrow highlighting.
Hiding a node hides its rows. Hiding a group hides its outline and label, not its children. Hiding an arrow hides its line, label, and arrowheads, but not its packets; use packet: false to hide those. Visibility does not change layout or implicitly hide connected elements. Arrowheads control appearance only; set back: true on a beat's edge to move its packet in reverse.
For a dotted storyboard connector, set line: dotted on the arrow element. The other line styles are solid and thick.
Optional add-ons
FlowMotion works out of the box. The optional draw.io editor is downloaded from its upstream project when you turn it on, and is not part of FlowMotion releases:
- draw.io editor for
.drawio.flowfiles, downloaded as the currentdraw.warfrom the draw.io GitHub releases (about 42 MB installed). To use it, open FlowMotion settings and turn it on. FlowMotion downloads it into the plugin folder (a network connection is needed once). Turn it off to delete the files. It works on the desktop app only.
FlowMotion uses CodeMirror for .flow files and the diagram edit window. It includes YAML syntax highlighting, line numbers, a live preview, and formatting with Shift+Alt+F. It works offline and on mobile without an add-on.
On desktop, enable Settings → FlowMotion → Rich Code Editor (Monaco) for completion, hover help, and navigation. The first enable downloads the pinned package published by the Monaco Editor project to npm. Reopen the diagram after installation. Monaco works offline after installation. See THIRD_PARTY_NOTICES.md for licenses.
Data access
- Opening the diagram picker enumerates
.flowfiles; it enumerates vault folders when showing the new-file destination list. Filtering the picker uses that opening-time file list. Path completion searches vault file names for.flow, YAML, and JSON files only when completing asrc:path. - The optional Monaco add-on includes clipboard support for editing and clipboard-aware suggestions. FlowMotion does not call the clipboard API directly.
- The optional draw.io editor is downloaded into the plugin folder through the vault adapter. A local server bound to
127.0.0.1serves those files to the editor.
Advanced
See the wiki for reusing diagram files, backgrounds, editor support, and build commands. The full YAML format is in Advanced: YAML format.
Status
See CHANGELOG.md for version history. Automated tests cover the drawing engine and selected Obsidian desktop workflows, including loading, SVG rendering, settings, and restart persistence. Mobile use and full optional-editor workflows still need manual checks. Test it in a copy of your vault first. See Known limitations.
Security
Pull requests to main, release/**, and hotfix/**, and pushes to main, run the repository's automated checks. The active main and release rulesets require the Security gate status check before merging. The Security checks workflow runs ESLint with the Obsidian plugin and security rules, build, typecheck, tests, Semgrep, Snyk Open Source and Code, SonarCloud, GitHub Dependency Review, and npm audit. The audit checks the full dependency lockfile, including development dependencies, and runs without secrets on fork pull requests. Credentialed Snyk scans check production and development dependencies at the medium severity threshold, with time-limited exceptions documented in .snyk. Snyk SARIF findings are uploaded to GitHub Code scanning. Public-fork pull requests run Semgrep Community Edition; Semgrep AppSec Platform, Snyk, and SonarCloud require repository secrets and are skipped for those PRs.
The SonarCloud quality gate shows the current server-side analysis result. Configure the repository's SONAR_TOKEN, SEMGREP_APP_TOKEN, and SNYK_TOKEN under Settings → Secrets and variables → Actions for the credentialed jobs to run. In Semgrep AppSec Platform, configure which findings are blocking; semgrep ci --no-suppress-errors fails the job on blocking findings and scanner errors. A scan result is evidence about that revision and scanner configuration; it does not prove the project is vulnerability-free.
Aikido and the IDE
The VS Code workspace recommends ESLint, Aikido Security, Semgrep, SonarQube for IDE, and Snyk Security. Install the recommendations when VS Code prompts, then sign in to each provider from its extension. SonarQube for IDE is bound to the SonarCloud project; complete the one-time connection in VS Code using the vrsarin connection and project vrsarin_obsidian-flowmotion.
Aikido's cloud PR checks are configured from the Aikido dashboard using its GitHub PR Checks app. To make Aikido findings block merges too, enable PR scans for this repository in Aikido and add the resulting Aikido check as a required status check in the main ruleset. Aikido's local-scanner GitHub Action is for local/on-prem scanning, so this workflow does not claim to run it. The Aikido dashboard may require sign-in; the public GitHub workflow and Code scanning pages provide public evidence for the checks that run in Actions.
To reproduce the repository lint locally, run npm ci and npm run lint. A clean lint run is evidence that the configured ESLint rules passed for that checkout; it does not replace the provider scan links above.
Contributing
Bug reports and ideas are welcome. Open an issue on GitHub.
Run make test-e2e to build the plugin and test it in downloaded Obsidian desktop builds.
On macOS, the E2E configuration prioritizes /usr/bin so installer setup uses Apple's xattr, not Python's incompatible command.
See the wiki for testing and examples and releases and CI.
License
See LICENSE.