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.
Links
- Repository: https://github.com/RohanAdwankar/oxdraw
- Mermaid documentation: https://mermaid.js.org
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 oxdraw2. Install dependencies
Rust (for CLI)
Make sure Rust is installed. If not:
curl https://sh.rustup.rs -sSf | shBuild the CLI:
cargo build --releaseNode.js (for the web interface)
Install frontend dependencies:
cd web npm installUsage
1. Create a diagram
Create a Mermaid file:
echo "graph TD; A-->B; B-->C;" > example.mmd2. Run the web interface
npm run devOpen 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.svgSupported 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.
