Summary

Oxdraw merges declarative diagramming (Mermaid) with interactive visual editing, targeting engineers and power users. It solves the need for reproducible, versionable diagrams by allowing visual refinements that are automatically saved back to the source code, bridging the gap between code-based tools and visual editors.

How It Works

A Rust CLI compiles Mermaid (.mmd) files to images (SVG, PNG) and enables interactive editing via a React frontend. Visual edits are persisted as declarative code comments in the source, ensuring determinism and versionability. The system also generates code maps from codebases using AI or static analysis.

Quick Start & Requirements

Install via Cargo: cargo install oxdraw. Render: oxdraw --input <file.mmd>. Edit: oxdraw --input <file.mmd> --edit. Code Map (AI): oxdraw --code-map ./ --gemini YOUR_API_KEY. Code Map (Static): oxdraw --code-map ./src/diagram.rs --no-ai. Requires Rust toolchain and potentially AI API keys.

Highlighted Details

• Interactive editor provides fine-grained control over node positions, edge routing, and styling.
• Visual changes are saved back to Mermaid source, maintaining tool compatibility.
• Supports AI-assisted or static analysis code map generation.
• Extensive CLI flags customize output formats, scaling, and editor hosting.

Maintenance & Community

Community engagement is encouraged via GitHub issues/discussions and social channels. An example integration is Typst-Oxdraw.

Licensing & Compatibility

The provided README does not specify a software license. Users must verify terms for adoption, especially for commercial use.

Limitations & Caveats

The path drawing algorithm is noted for ongoing improvements. AI code map generation requires external API access and configuration.