06.11.2025

How to use oxdraw: a visual editor for Mermaid diagrams with CLI and Rust support

oxdraw is a tool for creating and editing diagrams using a declarative syntax and with the ability for visual editing through a web interface. It is based on Mermaid, but allows not only writing diagram code, but also adjusting the appearance (positions, colors, lines, styles) directly in the interface, while all changes are automatically saved back to the original .mmd file as comments.
Thanks to this, diagrams remain deterministic, versionable, and compatible with other Mermaid tools.

oxdraw Features

Creation and editing of diagrams in Mermaid syntax
Visual editor with support for positioning, connections, and color schemes
Automatic saving of changes to the original .mmd file as comments
Rust CLI to compile .mmd → images (PNG, SVG, etc.)
Web interface built with React for interactive editing

Installation

1. Clone the repository

git clone https://github.com/RohanAdwankar/oxdraw.git cd oxdraw

2. Install dependencies

Rust (for CLI)

Make sure Rust is installed. If not:

curl https://sh.rustup.rs -sSf | sh

Build the CLI:

cargo build --release

Node.js (for the web interface)

Install frontend dependencies:

cd web npm install

Usage

1. Create a diagram

Create a Mermaid file:

echo "graph TD; A-->B; B-->C;" > example.mmd

2. Run the web interface

npm run dev

Open in your browser: http://localhost:5173

Load example.mmd and start editing — you can move nodes, change colors, styles, and connections.
All changes are automatically saved as comments in the file, for example:

graph TD
A-->B
B-->C
%% position: A(100,200), B(200,300)

Diagram Compilation

After editing, you can generate images:

cargo run --release -- example.mmd --output diagram.svg

Supported formats: SVG, PNG, and PDF.

Advantages of oxdraw

Full compatibility with Mermaid
Reproducibility and version control
Precise visual adjustment capabilities
Fast CI/CD integration for auto-generating diagrams in documentation

Example Use Case

Create a system architecture diagram in Mermaid
Open it in oxdraw and visually arrange the blocks
Save the file and commit it to Git
Use the CLI to generate final images for documentation

Conclusion

oxdraw is a tool that combines the convenience of visual editing with the flexibility of a declarative approach. It is especially useful for engineers, DevOps professionals, and technical writers who want to document infrastructure, system architecture, or CI/CD pipelines in clear and reproducible diagrams. With oxdraw, you can use the power of Mermaid together with the simplicity of a drag-and-drop interface without losing control over the code or compatibility with other tools. If you value determinism, transparency, and version control, oxdraw will be an excellent addition to your toolkit.

FAQ

What makes oxdraw better than regular Mermaid?
Regular Mermaid requires manual element positioning through code. oxdraw solves this problem by allowing you to edit the diagram visually and automatically save position changes back to the source file as comments — without losing compatibility.
Can I use oxdraw without the web interface?
Yes. The Rust-based CLI tool allows you to compile .mmd files into images without running the interface. This is useful for automation or CI/CD.
Where are the changes saved after visual editing?
All changes are written into the original .mmd file as comments (for example %% position: ...). This way, you can version and track differences in Git.
What export formats are supported?
With the CLI, you can export diagrams to SVG, PNG, or PDF, making oxdraw ideal for technical documentation and presentations.
Can oxdraw be integrated into existing projects?
Yes. oxdraw is fully compatible with Mermaid, so you can use it in existing projects without changing the diagram format.