# DOT to Mermaid

Convert Graphviz DOT source into Mermaid flowchart syntax in your browser: nodes, edges, labels, shapes, clusters, colors and direction. Nothing is uploaded.

## Run it

- **CLI:** `gizza tool dot-to-mermaid 'digraph {
  rankdir=LR;
  start [label="Start", shape=circle];
  check [label="Tests pass?", shape=diamond];
  start -> check [label="build"];
  check -> ship [label="yes"];
  check -> fix [label="no", style=dashed];
}'`
- **Web:** https://gizza.ai/tools/dot-to-mermaid/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/dot-to-mermaid/tool.json

## Inputs

- `dot` — Graphviz DOT source _(field)_
- `direction` — Flowchart direction _(field)_
- `shapes` — Map node shapes (box, circle, diamond, cylinder…) _(field)_
- `edge_labels` — Keep edge labels _(field)_
- `link_styles` — Map edge styles (dashed, bold, arrowless, bidirectional) _(field)_
- `subgraphs` — Convert cluster_* subgraphs _(field)_
- `colors` — Convert colors to style / linkStyle lines _(field)_
- `warnings` — Add %% notes for unsupported DOT features _(field)_
- `title` — Diagram title (optional) _(field)_
- `fence` — Wrap in a ```mermaid code fence _(field)_

## Output

- Mermaid source (text)

## Query parameters

Open the tool pre-filled and auto-run via URL:

- `dot` — Graphviz DOT source
- `direction` — Flowchart direction
- `shapes` — Map node shapes (box, circle, diamond, cylinder…)
- `edge_labels` — Keep edge labels
- `link_styles` — Map edge styles (dashed, bold, arrowless, bidirectional)
- `subgraphs` — Convert cluster_* subgraphs
- `colors` — Convert colors to style / linkStyle lines
- `warnings` — Add %% notes for unsupported DOT features
- `title` — Diagram title (optional)
- `fence` — Wrap in a ```mermaid code fence

Example: `https://gizza.ai/tools/dot-to-mermaid/?dot=digraph%20%7B%0A%20%20rankdir%3DLR%3B%0A%20%20start%20%5Blabel%3D%22Start%22%2C%20shape%3Dcircle%5D%3B%0A%20%20check%20%5Blabel%3D%22Tests%20pass%3F%22%2C%20shape%3Ddiamond%5D%3B%0A%20%20start%20-%3E%20check%20%5Blabel%3D%22build%22%5D%3B%0A%20%20check%20-%3E%20ship%20%5Blabel%3D%22yes%22%5D%3B%0A%20%20check%20-%3E%20fix%20%5Blabel%3D%22no%22%2C%20style%3Ddashed%5D%3B%0A%7D&direction=auto&shapes=true&edge_labels=true&link_styles=true&subgraphs=true&colors=true&warnings=true&title=Release%20pipeline&fence=true`

---

## About this tool

Graphviz DOT and Mermaid flowcharts solve the same problem with different syntax. DOT is common in build tools, dependency analyzers and older architecture docs; Mermaid is what many README files, issue trackers and knowledge bases render natively. This converter rewrites the DOT graph into Mermaid source so you can keep the structure without redrawing the diagram by hand.

Paste a `graph { ... }` or `digraph { ... }` document and the converter parses it locally in WebAssembly. It keeps node IDs, quoted labels, chained edges, graph/node/edge defaults, cluster subgraphs, `rankdir`, selected node shapes, edge labels, dashed/bold/bidirectional links and common color attributes. Features with no Mermaid equivalent are kept as `%%` notes so the output is honest rather than silently lossy.

### Worked example

Input DOT:

```dot
digraph {
  rankdir=LR;
  start [label="Start", shape=circle];
  check [label="Tests pass?", shape=diamond];
  start -> check [label="build"];
  check -> ship [label="yes"];
  check -> fix [label="no", style=dashed];
}
```

Default output:

```mermaid
flowchart LR
  start(("Start"))
  check{"Tests pass?"}
  start -->|build| check
  check -->|yes| ship
  check -.->|no| fix
```

Turn off **Keep edge labels** when you only want the graph structure, or enable **Wrap in a code fence** to paste the result directly into Markdown:

````markdown
```mermaid
flowchart LR
  start(("Start"))
  check{"Tests pass?"}
  start --> check
```
````

### Limits and edge cases

- DOT input is capped at 1 MiB, 2,000 distinct nodes and 5,000 edges so browser conversions stay responsive.
- The converter targets Mermaid `flowchart`, not sequence/class/state diagrams. DOT layout attributes such as `pos`, `splines`, `rank=same`, exact sizes and fonts do not have a direct Mermaid equivalent.
- `rankdir=TB/LR/BT/RL` maps to Mermaid direction; the **Flowchart direction** control can override it.
- Mermaid has fewer node shapes than Graphviz. Common shapes are mapped and unknown ones fall back to rectangles with a `%%` note when warnings are enabled.
- Cluster subgraphs become Mermaid `subgraph ... end` blocks. Non-cluster anonymous grouping is flattened unless it is needed to expand edges.
- DOT ports (`node:port`) are parsed so edges still land on the node, but port-specific attachment points are reported as unsupported because Mermaid flowcharts do not expose them.

## FAQ

<details>
<summary>Can it convert every Graphviz diagram perfectly?</summary>

No. DOT can describe precise renderer layout, fonts, ports, record fields and Graphviz-only shapes that Mermaid flowcharts cannot express. This tool converts the graph structure and the common presentation hints that Mermaid supports, then lists the rest as `%%` comments so you can decide what to adjust manually.

</details>

<details>
<summary>Does it run Graphviz or upload my DOT source?</summary>

No. It uses a small parser compiled to WebAssembly and runs entirely in the browser. That keeps private architecture graphs local, but it also means the tool converts syntax instead of rendering DOT through Graphviz's layout engine.

</details>

<details>
<summary>What happens to labels and special characters?</summary>

Quoted DOT labels are carried into Mermaid labels and escaped for Mermaid's bracket syntax. HTML-like labels are reduced to readable text where possible; advanced table-like HTML labels are not recreated exactly because Mermaid flowcharts do not support Graphviz HTML label tables.

</details>

<details>
<summary>How should I handle a graph that uses clusters?</summary>

Leave **Convert cluster_* subgraphs** enabled. Subgraphs named `cluster_api` or carrying a `label=` become Mermaid subgraphs, including nested clusters. Disable the option if the extra grouping makes the Mermaid source too noisy and you only need the nodes and edges.

</details>

<details>
<summary>Why are my node IDs different in the Mermaid output?</summary>

Mermaid IDs cannot contain every character DOT permits. Unsafe IDs are sanitized, and the original text is preserved as a label when that matters. This keeps the Mermaid parseable while still showing the names from the DOT file.

</details>

## Related tools

- [JSON to Graph](https://gizza.ai/tools/json-to-graph/): Turn JSON into a node-link graph as Mermaid flowchart or Graphviz DOT. Collapse deep branches, cap arrays and generate paste-ready diagram source in your browser.
- [Apply a Unified Diff to a File](https://gizza.ai/tools/apply-patch/): Paste a file and a unified diff to get the patched text in your browser, with reverse apply, fuzz matching, and per-hunk conflict reports.
- [Autocomplete Trie](https://gizza.ai/tools/autocomplete-trie/): Build a prefix trie from a pasted wordlist and get ranked autocomplete suggestions for any typed prefix. Weights, typo tolerance, trie stats, JSON. Runs locally.
- [Code Chunker](https://gizza.ai/tools/code-chunker/): Split Python, Rust, JavaScript, TypeScript, Go, Java, C/C++, C#, PHP, or Swift into line-ranged chunks that keep functions and classes intact.
- [Code Formatter](https://gizza.ai/tools/code-formatter/): Beautify and re-indent minified or messy HTML, CSS, JavaScript, or JSON. Auto-detect the language, choose spaces or tabs, and format locally in your browser.