oxdraw: a Mermaid renderer with an editor that writes back to your source file

Rendering a diagram without opening a browser

oxdraw is a Rust program that reads a `.mmd` file and writes an image, with a web editor layered on top of the same rendering engine. The install is a single Cargo invocation:

cargo install oxdraw

Rendering one file is one command:

oxdraw --input flow.mmd

The flag table in the README is unusually complete for a project this young, and it is worth reading because it documents several behaviours you would otherwise discover by trial. Output defaults to `<input>.svg`, and passing `-` to the output flag streams SVG to standard output, which is what you want when the renderer is a build step. `-` on the input side reads Mermaid from standard input instead of a file, and the default output name changes to `out.svg` in that case. A `--png` shorthand sets the output format, and `--scale` multiplies rasterization resolution, defaulting to `10.0`.

Two flags only apply while the editor is running: `--serve-host` overrides the bind address, which defaults to `127.0.0.1`, and `--serve-port` overrides the port, which defaults to `5151`. That default of localhost is worth noting, because it means the editor is not exposed to your network unless you ask for it.

Launching the editor on a file

Adding `--edit` turns the same command into a local editing session:

oxdraw --input flow.mmd --edit

The interesting part is what happens when you drag something. The README describes the design as declarative: Mermaid text remains the source of truth, and when you adjust a position, a connector path, or a color in the web interface, the change is persisted back into the `.mmd` file as declarative code rather than into a separate layout file. Concretely, those adjustments are stored as comments inside the Mermaid file, which is what keeps a diagram readable by other Mermaid tooling that has never heard of oxdraw.

That constraint is the whole argument for the project. The author's stated motivation is that diagrams written as Mermaid could not be tidied up by hand, so work migrated to a dedicated diagramming application, and the goal was to keep code generation as the entry point while recovering direct manipulation as an option. If you have ever ended up maintaining the same architecture diagram twice, once as generated text and once as a polished picture, this is the specific problem oxdraw targets.

Sharing is handled in two ways, and both are simple. You can export the result as a PNG or SVG, or you can use the share button on the static site, which writes the diagram into the URL hash fragment so a colleague can open the same diagram and edit it.

Pointing diagram nodes at lines of source code

The codemap feature links nodes in a diagram to segments of a codebase, and the README frames it as a way to navigate a repository rather than merely document it. Point it at a directory:

oxdraw --code-map ./ --gemini YOUR_API_KEY

Passing an API key is optional in the sense that the tool still runs without one, but the flag itself is how you request model assistance, and the code is written to work against an OpenAI compatible endpoint as well as Gemini, including a locally hosted model. Documentation for the setup lives in `docs/ai.md`, which the README links as the place to find free resources.

When you would rather see the feature without involving a model at all, there is a static analysis path that takes a single file or directory:

oxdraw --code-map ./src/diagram.rs --no-ai --output test.png

The release notes for v0.2.0 describe how this was tightened: codemaps can map nodes to code segments through line numbers or through definitions, a file viewer was added so you can read the source inline with the relevant segment highlighted and scrolled into view, and shift-clicking a node opens the file in an editor, defaulting to Vi or VSCode. Conditional node support arrived in the same release. A routing change also landed, with the algorithm now preferring orthogonal routes, which is the difference between connectors that read as intentional and ones that cut diagonally across unrelated boxes.

Codedowns and patching up markdown you already have

A codedown is a markdown document carrying mapping metadata, and the README describes the intent as making headings, paragraphs, and inline code clickable in a way that jumps into the codebase. Generation and viewing are separate operations, so the same content can be produced by a model and then reviewed as plain text before it is ever opened in the viewer.

oxdraw --codedown ./ --codedown-style architecture --gemini YOUR_API_KEY --prompt "Focus on auth + request lifecycle"

The `--codedown-style` flag picks a built in prompt preset, and the README names three: `architecture`, `tutorial`, and `api`. Anything you append to `--prompt` is added to that preset, which is the practical way to narrow a generated document without rewriting the request from scratch. Sending the result to a file or to standard output rather than launching the viewer is done through `--output`:

oxdraw --codedown ./ --codedown-style api --gemini YOUR_API_KEY --output docs/architecture.md

Passing `-` as the output path prints to standard output, which is the version to use if you want to pipe the document through your own tooling. Pointing `--input` at a markdown file that already contains codedown mappings opens the codedown viewer instead of trying to parse it as Mermaid.

For documents that already exist, `--augment-markdown` adds mappings to a file in place, writing `<stem>-mapped.md` by default:

oxdraw --augment-markdown docs/notes.md --repo-path . --gemini YOUR_API_KEY

Beyond the mappings you ask for explicitly, the README notes that inline code blocks are mapped to their definitions and filenames to the relevant file automatically.

What the Cargo manifest says about the design

The manifest is short enough to read in one sitting and settles several questions the README leaves open. Two binaries are declared, `oxdraw` itself and `view_visual_diff`, the latter living in `utils/view_visual_diff.rs`, so there is a separate tool for inspecting visual differences between renders. The library target is built as both a C dynamic library and a Rust library:

[lib]
name = "oxdraw"
crate-type = ["cdylib", "rlib"]
path = "src/lib.rs"

The `cdylib` entry is the one that matters for the deployment claim. The README states that the Rust algorithm compiles to WebAssembly, which is what allows the editor to be hosted as a static site with no server behind it. `wasm-bindgen` and `serde-wasm-bindgen` are declared only for `wasm32` targets, and the default `server` feature pulls in `axum`, `tokio`, `tower-http`, and `tower`, which is the server used during `--edit`. Turning that feature off leaves you with the renderer and no editor.

The dependency list is worth noting for a different reason: `resvg` with the `text` feature and `tiny-skia` with `png` are the rasterization path, `clap` handles the flags, and `walkdir` is what makes repository-wide codemaps possible. The tree matches the README's description of the layout, with `frontend/` holding the React editor, `docs/` holding the AI setup notes, and `tests/` holding Rust tests that use `assert_cmd`, `libtest-mimic`, and `similar-asserts`.

Where the version numbers and the release history disagree

Two version signals are visible in the repository and they do not match, which matters if you are pinning a dependency or filing an issue. `Cargo.toml` declares `version = "0.2.1"`, while the newest published release is `v0.2.0`, cut on 2025-11-28. A `cargo install oxdraw` therefore pulls whatever crates.io currently serves, which may be ahead of or behind the code tied to a specific GitHub release tag. If you need to match a bug report to a build, the commit and the tag are the reliable pair rather than the manifest version.

The language metadata also gives a partial picture. GitHub reports the repository as Rust, and the renderer, the CLI, and the codemap logic are all Rust, but the README describes the editing surface as React and the tree has a `frontend/` directory to match. A project like this is naturally two codebases in one repository, and reading the tree rather than the language field avoids concluding that there is no frontend.

Activity is current rather than historical: the last push was on 2026-09-26, and the repository is not archived, with 2,351 stars and 87 forks. The open issue count of 27 against that star count suggests a project with a following and a real queue, which is worth weighing if you are deciding whether to depend on it. The published homepage is a working editor, so you can evaluate the layout behaviour against your own diagram before installing anything.

Editorial conclusion

oxdraw is at its best when a diagram needs to survive code review, because every nudge in the web editor lands in the Mermaid file as a comment rather than as pixels. The static site at rohanadwankar.github.io/oxdraw is the fastest way to judge whether the layout model fits your diagrams, and cargo install oxdraw gives you the CLI for the same engine. What the repository does not settle is how far the AI codemap path can be trusted without review, since a wrong line number looks exactly like a right one, and it does not say which Rust version or Mermaid revision a given build targets. Start with a single diagram through the editor, then check the diff before committing anything a machine proposed.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. RohanAdwankar/oxdraw on GitHub