The Ultimate Diagramming Tool! Creating a Draggable Mermaid Editor with Rust

Have you ever had this experience?

After painstakingly writing a bunch of architecture diagrams and flowcharts with Mermaid, you send them to your colleagues, and they respond: “Hey, can you move this node a bit to the left?” “Can this line bend a bit instead of overlapping the text?” “The colors are too dull, add some highlights!”

Then you just feel like collapsing—moving one position means readjusting the entire layout; trying to avoid crossing lines turns the diagram into a spider web; after finally getting it right, refreshing the page resets everything back…

Even more absurd is that you can only rely on constantly modifying text parameters to “blindly adjust” without seeing real-time effects. This isn’t drawing; it’s writing “graphical spells”!

But today, I want to tell you: the era of guessing and trial-and-error for drawing diagrams may be coming to an end.

Recently, a dark horse emerged on GitHub called <span>oxdraw</span>— a Diagram-as-Code tool written in Rust, which has done something quite “rebellious”:

It allows you to declare the structure of diagrams like writing code, while also enabling you to drag and adjust details like using Lucidchart, and all changes are automatically saved back to the code!

Doesn’t that sound a bit magical? Don’t worry, today we will take a good look at this project and see how it reconciles the “code generation” and “visual editing” that are usually at odds.

Are you ready? Let’s start with a meal.

1. The Lunch Dilemma of Programmers: Why Does Mermaid Always Seem “Just a Bit Off”?

Imagine this: it’s lunchtime, and you’re at the company cafeteria.

You want to tell the new intern: “The data flow of our system is like this: user requests first go to the API gateway, then into the authentication service, then through the business logic layer, and finally into the database.”

So you pull out your notebook, open VS Code, and type out a segment of Mermaid:

graph LR
    A[用户请求] --> B(API网关)
    B --> C{是否登录?}
    C -->|是| D[认证服务]
    C -->|否| E[跳转登录页]
    D --> F[业务逻辑层]
    F --> G[(数据库)]

You export the image, send it to the group, captioning: “Look, this is our core link.”

Then a colleague replies: “Dude, node C is too far to the right, D and F are not aligned; and can that line not go through the text? It looks like a bug.”

Inside, you feel a thousand thoughts racing: I just wanted to express the logical relationship, who cares about alignment?

But the reality is, a diagram not only needs to be “correct” but also “aesthetically pleasing.” Otherwise, others will think at first glance: “This person is not serious about their work.”

So you start trying to add <span>%%{init}</span> initialization configurations, setting <span>nodeSpacing</span>, <span>rankSpacing</span>, and even manually inserting empty nodes as placeholders… In the end, the diagram is adjusted, but the code is unrecognizable, even you can’t understand it anymore.

At this point, you realize: The pain point of Mermaid is not that it can’t draw diagrams, but that it lacks fine control.

It is suitable for rapid prototyping but not for deliverable documentation.

And what if you switch to tools like Lucidchart or ProcessOn? They can drag and drop, adjust styles, but the problem is—

These diagrams cannot be placed in Git repositories for version control!

Every time you change an interface, you have to reopen the webpage, find the corresponding diagram, manually modify it, then take a screenshot and upload it. Over time, the diagrams in the documentation become disconnected from the actual system.

So the question arises:

Is there a way to maintain diagrams like writing code (versionable, reproducible), while also allowing free editing like graphic software (draggable, adjustable)?

Now, the answer is here: oxdraw.

2. What is oxdraw? In a nutshell: Mermaid + Draggable Editor + Automatic Code Synchronization

Let’s first look at the official definition:

oxdraw is a Diagram-as-Code tool based on Rust that supports writing diagrams using Mermaid syntax and provides a web interface for drag-and-drop interactive editing. The key point is: any visual adjustments you make in the interface (like moving nodes, adding control points, changing colors) will be automatically saved back to the original <span>.mmd</span> file as comments, ensuring that the code and view are completely synchronized.

Sounds impressive? Let’s break it down.

It consists of two parts:

1. CLI tool written in Rust responsible for rendering <span>.mmd</span> files into SVG or PNG images, and can also start a local server to run the front-end editor.

2. Web front-end editor implemented in React provides a visual drag-and-drop interface, supporting node movement, line rerouting, style overrides, and more.

The two are connected through a clever design: all visual modifications do not change the original syntax structure of Mermaid but are written into the file as comments in a special format.

This means:

✅ You can continue to describe logical structures using Mermaid syntax✅ At the same time, you can have fine control capabilities at the level of graphic editors✅ More importantly: this <span>.mmd</span><span> file is still plain text, which can be submitted to Git, diffed, and automated for builds</span>

In other words, oxdraw is not replacing Mermaid; it is giving it “wings”.

3. Hands-On Experience: Installation & Usage Process

Enough talk, let’s get hands-on right away.

Step 1: Install oxdraw

The prerequisite is that you need to have a Rust environment (if you haven’t installed it, please search for the <span>rustup</span> installation tutorial).

Then one command will do:

cargo install oxdraw

After installation, entering <span>oxdraw --help</span> should show you help information like below:

USAGE:
    oxdraw [OPTIONS]

OPTIONS:
    -i, --input <PATH>           Input Mermaid file path
    -o, --output <PATH>          Output image path
    --png                        Output as PNG format
    --scale <FACTOR>             PNG rendering scale factor (default 10.0)
    --edit                       Start interactive editor
    --serve-port <PORT>          Editor server port (default 5151)
    -b, --background-color       Set background color
    -q, --quiet                  Silent mode

Step 2: Prepare a Test File <span>flow.mmd</span>

Create a simple flowchart:

graph TD
    A[开始] --> B{条件判断}
    B -->|满足| C[执行操作]
    B -->|不满足| D[记录日志]
    C --> E[结束]
    D --> E

Save it as <span>flow.mmd</span>.

Step 3: Render Directly to Image

Run the command:

oxdraw --input flow.mmd --png

You will find a new <span>flow.png</span> in the current directory, which is clear and sharp, with ultra-high resolution (because it defaults to 10x scaling for rendering).

If you want SVG:

oxdraw --input flow.mmd

It will generate <span>flow.svg</span>, which is convenient for embedding in web pages or further editing.

Step 4: Enter the Magical Feature—Drag-and-Drop Editing Mode!

Here comes the key part! Run:

oxdraw --input flow.mmd --edit

The terminal will prompt:

🚀 Editor server started at http://127.0.0.1:5151
📝 Opening browser... (press Ctrl+C to exit)

The browser will automatically pop up, showing a clean and modern editing interface:

On the left is the Mermaid source code editing area, and on the right is the interactive canvas.

You can now:

• 🖱️ Drag any node, and they will automatically snap to the grid
• ✚ Double-click on a line to add control points and manually pull out a polyline path
• 🎨 Click on nodes or lines to pop up a color palette to modify fill color, border, and text color
• ➿ Switch arrow directions and line styles
• 🗑️ Select an element and press Delete to remove it

The most amazing part is: Every time you drag a node, the code area on the left changes as well!

Although the main structure remains the original Mermaid syntax, a segment of comments is added at the end of the file:

%% oxdraw:positions
%% A: (120, 80)
%% B: (240, 80)
%% C: (360, 40)
%% D: (360, 120)
%% E: (480, 80)

%% oxdraw:edges
%% B-->C: M240,90 C300,90 300,40 360,40
%% B-->D: M240,90 C300,90 300,120 360,120

Did you see that? These are all the position coordinates and path information automatically generated by oxdraw!

This means, every visual adjustment you make is converted into machine-readable metadata, permanently stored in the file.

The next time you open this file, whether rendering in CLI or viewing in the editor, it will revert to the last adjusted state.

This is the true meaning of “what you see is what you get + versionable”.

4. Core Technology Revealed: How Does It Achieve “Code ↔ View” Bidirectional Synchronization?

You might think this is just a front-end toy? Wrong, there is a whole set of sophisticated technical designs behind it.

Let’s delve into the three core technology modules of oxdraw.

1. Parsing Layer: Mermaid AST Extraction + Custom Metadata Injection

oxdraw does not implement its own Mermaid syntax parser but reuses the mature <span>mermaid-js</span> engine from the community.

However, its cleverness lies in: after parsing the standard syntax, it additionally extracts “non-functional” layout information and isolates it for storage.

The specific approach is:

• The main logic is still parsed by the native Mermaid to ensure compatibility
• All custom styles, positions, paths, etc., are uniformly wrapped in comment blocks starting with <span>%% oxdraw:xxx</span>
• During rendering, the original Mermaid structure is loaded first, and then the layout offsets injected by oxdraw are applied

The benefits of this approach are:

🔧 Complete compatibility with other Mermaid tools Even if you take the <span>.mmd</span> file to render elsewhere, those comments will be ignored, and the diagram will still display normally (just reverting to the default layout)

🔒 Avoid polluting the semantic structure It does not rewrite the <span>graph</span> or <span>subgraph</span> structures to control styles, keeping the code clean

🧠 Implement an “incremental update” mechanism only synchronizing the changed parts instead of rewriting the entire file

2. Rendering Engine: High-Performance Combination of Rust + WebAssembly

Many people see “front-end editor” and think this is a pure JS project, but in fact, the core rendering logic of oxdraw is written in Rust!

It compiles Rust into a binary module that can run in the browser using WASM (WebAssembly) technology, responsible for the following tasks:

• Mermaid string → SVG path calculation
• Control point interpolation algorithm (Bezier curve optimization)
• Collision detection and automatic avoidance (future planning feature)
• Graph transformation matrix calculations

Why use Rust?

Because this type of graphical computation is very performance-intensive, especially when dealing with complex topological structures, JavaScript’s GC and dynamic typing disadvantages are evident.

Rust provides three major advantages: zero-cost abstraction, memory safety, and extreme performance, making it particularly suitable for building low-level graphics engines.

For example: when you drag a node, all edges connected to it need to be redrawn in real-time. If implemented in JS, frequent array operations and DOM updates can easily cause lag.

But in oxdraw, this logic runs in WASM, with millisecond-level response times, smooth as silk.

3. Bidirectional Binding Mechanism: Virtual DOM + File Watching + Automatic Saving

To achieve true bidirectional synchronization between “code ↔ view”, oxdraw has designed a state management system similar to React + Redux.

The workflow is as follows:

[User drags a node]
      ↓
Trigger front-end event → Send to WASM module to calculate new coordinates
      ↓
WASM returns new layout data → Update React state tree
      ↓
React re-renders the canvas + synchronously updates the left code panel
      ↓
Debounce timer triggers → Write changes back to disk file

Key details include:

• Using <span>throttle/debounce</span> to prevent frequent disk writes
• Diffing only writes changed parts, reducing I/O
• Supports <span>stdin/stdout</span> streaming, facilitating CI/CD integration
• Error boundary handling to prevent data loss due to editor crashes

This mechanism may seem simple, but it actually involves the collaboration of multiple technology stacks: Rust, WASM, React, WebSocket, FS Watcher…

But what is ultimately presented to the user is just a <span>.mmd</span> file + a command.

This is the charm of excellent tools: complexity hidden behind the scenes, simplicity presented to the eye.

5. Advanced Features: Not Just Drag-and-Drop, But More!

You think oxdraw is just a “drag-and-drop Mermaid editor”? Too naive.

Let’s look at some impressive advanced uses.

🌟 Using oxdraw for “AI-Generated Diagrams + Manual Refinement” Pipeline

Many AI tools (like Cursor, Claude, Tongyi Qianwen) can now generate Mermaid code based on descriptions.

But the problem is: AI-generated diagrams often have chaotic layouts, crowded nodes, and crossed lines.

At this point, you can do the following:

1. Let AI generate the initial <span>.mmd</span> file
2. Open it with <span>oxdraw --edit</span>, manually tidy up the layout
3. After saving, everyone who sees it later will see the optimized version
4. Even if the original AI prompt is lost, it won’t affect the diagram’s usability

This effectively establishes a standardized process of “AI draft → manual polishing → version retention”.

🌟 Ensuring “Visual Consistency” in Collaborative Scenarios

What do teams fear most when writing documentation? Inconsistent styles.

Some prefer horizontal layouts, others vertical; some use blue to represent services, others green…

Using oxdraw can solve this problem:

• Place a <span>template.mmd</span> in the project root directory, pre-setting common node styles and layout rules
• Every time a new diagram is created, it is copied based on the template
• Everyone operates under the same visual standards while editing
• During PR submissions, a lint tool can check for illegal style overrides

Over time, the style of diagrams across the entire project will tend to be consistent.

🌟 Automated Document Generation Pipeline

By combining GitHub Actions, you can set up an automated process like this:

name: GenerateDiagrams

on:[push]

jobs:
build:
    runs-on:ubuntu-latest
    steps:
      -uses:actions/checkout@v4

      -name:Installoxdraw
        run:cargoinstalloxdraw

      -name:Renderall.mmdfiles
        run:|
          find . -name "*.mmd" | while read f; do
            oxdraw --input "$f" --png --scale 5
          done

      -name:Commitandpushimages
        run: |
          git config user.name "github-actions"
          git add *.png
          git commit -m "Auto-generate diagrams" || exit 0
          git push

From now on, as long as you submit a <span>.mmd</span> file, the corresponding high-definition PNG will be automatically generated and pushed back.

No more manual exporting, screenshotting, and uploading.

🌟 Intelligent Group Movement of Subgraph Containers

oxdraw supports the <span>subgraph</span> feature of Mermaid, for example:

graph TD
    subgraph 用户系统
        U1[登录]
        U2[注册]
        U3[忘记密码]
    end

    subgraph 订单系统
        O1[下单]
        O2[支付]
        O3[发货]
    end

    U1 --> O1

In the editor, you can directly drag the entire “User System” box, and the three nodes inside will move together, maintaining their relative positions.

Even more impressive is: all lines originating from this subgraph will automatically adjust their paths!

This kind of “subgraph-level operation” greatly enhances the organizational efficiency of large diagrams.

6. The Philosophy Behind: What Problems Does Diagram as Code Solve?

After discussing so many technical details, let’s take a step back and think about a question:

Why do we insist on “drawing diagrams with code”? Isn’t it better to use PPT directly?

In fact, “Diagram as Code” is not just for show; it aims to solve four major pain points in the real world:

Pain Point	Traditional Graphic Tools	Diagram as Code
❌ Version Control Issues	Screenshots cannot be diffed, and you don’t know what changed	Text files can be managed with Git, precisely tracking every change
❌ Collaboration Difficulties	Multiple editors need to pass files, which can easily overwrite	Branch merging + PR Review, standardizing the process
❌ Automation Challenges	Cannot be scripted for generation or batch processing	Can integrate CI/CD, generating a full set of documents with one click
❌ Low Reusability	Every time you have to redraw similar structures	Template-based, variable replacement, include mechanisms

The emergence of oxdraw adds another column to the existing foundation:

New Value	Implementation Method
✅ Fine Control	Drag-and-drop editing + style overrides
✅ What You See Is What You Get	Real-time preview + bidirectional synchronization
✅ Lowering the Barrier	No need to memorize complex CSS class names or layout parameters

It retains the “code-first” engineering advantages while compensating for the “lack of interactivity” experience shortcomings.

This is the true balance of “ideal and reality”.

7. Comparing Similar Tools: Why Does oxdraw Stand Out?

There are many similar tools on the market, let’s do a horizontal comparison.

Tool	Technology Stack	Supports Drag-and-Drop	Retains Code	Open Source	Cross-Platform
Mermaid Live Editor	JS	❌	✅	✅	✅
PlantUML + IntelliJ Plugin	Java	⚠️ Limited	✅	✅	✅
Draw.io / diagrams.net	JS	✅	❌ (XML Encapsulation)	✅	✅
Excalidraw	TS	✅	⚠️ (JSON + Mixed Code)	✅	✅
oxdraw	Rust + WASM	✅	✅ (Comment Injection)	✅	✅

It can be seen that oxdraw is currently the only tool that truly achieves the integration of “pure text source code + fully visual editing + automatic bidirectional synchronization”.

Especially its choice to implement the core engine in Rust, rather than Node.js or Python, indicates that the author is pursuing long-term performance and stability rather than short-term rapid iteration.

It is worth noting that in 2025, if someone is still willing to write a graphics tool in Rust, it shows their dedication to engineering quality.

8. Future Prospects: How Can oxdraw Evolve?

Although oxdraw is still in its early stages (only two months since its creation on GitHub, with 883 stars), its potential is enormous.

I predict it may develop in the following directions:

🔮 1. Support for More Diagram Types

Currently, it mainly supports Flowcharts, but it is expected to expand to:

• Sequence Diagrams
• Class Diagrams
• Gantt Charts
• Mindmaps

As long as Mermaid supports it, it can theoretically be integrated.

🔮 2. Introduce AI-Assisted Layouts

Imagine this: after you draw the nodes and lines, you click “AI Layout”, and the system automatically analyzes semantic relationships to provide the optimal layout scheme.

For example, clustering frequently called services together, expanding asynchronous processes horizontally, etc.

🔮 3. Support for Theme Systems

Similar to CSS themes, define a <span>.theme</span> file to switch between day/night modes, tech styles/hand-drawn styles, flat/3D effects, etc.

🔮 4. Plugin Ecosystem

Open API to allow developers to write plugins, such as:

• Automatically generate API call flow diagrams
• Import interface relationships from OpenAPI specs
• Integrate with Confluence/Jira to automatically update documentation

Once an ecosystem is formed, oxdraw will no longer just be a tool but an “intelligent diagram platform”.

9. Conclusion: We Are Witnessing the Birth of the “Next Generation Documentation Paradigm”

Looking back ten years ago, we were still using Word for documentation; five years ago, we began transitioning to Markdown; and now, we are at a new turning point:

The future of documentation is not only “readable” but also “computable”.

And oxdraw is a typical representative of this trend.

It tells us:

• Diagrams should not be static images but dynamic and evolvable data structures
• Design should not rely on personal aesthetics but should be based on reproducible rules
• Collaboration should not depend on screenshots for communication but should reach consensus through code reviews

Perhaps one day, when we look back at this history, we will find:

It is tools like oxdraw that have transformed “drawing diagrams with code” from a geeky toy into an industry standard.

So, stop enduring those messy diagrams.

Go try <span>oxdraw</span> now.

Who knows, the next stunning technical solution diagram you create might just be made with it.

Appendix: Common Command Quick Reference

Scenario	Command
Install oxdraw	<span>cargo install oxdraw</span>
Render PNG	<span>oxdraw --input demo.mmd --png</span>
Render SVG	<span>oxdraw --input demo.mmd</span>
Start Editor	<span>oxdraw --input demo.mmd --edit</span>
Modify Port	<span>oxdraw --input demo.mmd --edit --serve-port 8080</span>
Set Background Color	<span>oxdraw --input demo.mmd -b "#fff"</span>
Silent Output	<span>oxdraw --input demo.mmd -q</span>
Read from stdin	<span>cat diagram.mmd | oxdraw -i - -o out.png</span>

📌 Project Address:https://github.com/RohanAdwankar/oxdraw^[1]

References

[1]

https://github.com/RohanAdwankar/oxdraw: https://github.com/RohanAdwankar/oxdraw