Diagrams Beyond Mermaid (Graphviz + PlantUML)

Mermaid is great for many diagrams, but sometimes you need Graphviz or PlantUML. md2docx supports both syntaxes in fenced code blocks and renders them to images embedded in your DOCX.

If you self-host md2docx, you’ll need the corresponding renderer tools installed. If rendering fails, md2docx falls back to including the code block so you can still ship a document.

This guide focuses on practical patterns that convert well to Word: diagrams that fit on a page, labels that stay readable, and syntax that’s easy to maintain in a Markdown workflow.

When to use Graphviz vs PlantUML

Both tools are “diagrams as code”, but they shine in different scenarios:

Graphviz is great for graph layouts: dependency graphs, state machines, and node/edge diagrams where layout algorithms do the heavy lifting.
PlantUML is great for structured diagrams: sequence diagrams, component diagrams, and architecture views where you want a more opinionated grammar.

If your team already uses Mermaid, keep using it for simple docs and reach for Graphviz/PlantUML when Mermaid syntax becomes limiting (see also Mermaid diagrams).

Graphviz / DOT

Use a fenced block labeled graphviz:

```graphviz
digraph G {
  rankdir=LR;
  A -> B;
  B -> C;
}
```

Tip: keep labels short and prefer left-to-right diagrams only when you have enough page width.

A more “report-ready” Graphviz example

When you’re documenting systems, clusters and labels help the diagram read like a narrative instead of a pile of nodes:

```graphviz
digraph Architecture {
  rankdir=LR;
  node [shape=box, style=rounded];

  subgraph cluster_client {
    label=\"Client\";
    Browser;
  }

  subgraph cluster_app {
    label=\"Application\";
    API;
    Worker;
  }

  Browser -> API [label=\"HTTPS\"];
  API -> Worker [label=\"jobs\"];
}
```

Keep the number of nodes limited per diagram. If labels start shrinking, split the diagram into two smaller ones and place them near the relevant text.

PlantUML

Use a fenced block labeled plantuml:

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi!
@enduml
```

PlantUML is especially useful for sequence diagrams and component diagrams when you want a strict syntax.

Sequence diagrams (a common Word use case)

```plantuml
@startuml
actor User
participant \"Web App\" as Web
participant API
database DB

User -> Web: Submit request
Web -> API: POST /convert
API -> DB: Record metadata
API --> Web: DOCX download
Web --> User: Save file
@enduml
```

Sequence diagrams tend to fit well on a Word page because they’re mostly vertical. If you have a very wide participant list, shorten names or split the flow into phases.

Make diagrams readable in Word

Prefer portrait-friendly layouts unless you truly need wide diagrams.
Keep labels short and move long explanations into the surrounding text.
Split large diagrams into smaller diagrams aligned with section headings.
If you must use a wide diagram, use section breaks to create a landscape section (see Advanced conversion options).

The best diagrams for Word are the ones a reviewer can understand without zooming. Treat each diagram as a figure with a purpose, not a dumping ground of every node in the system.

Troubleshooting

If a diagram renders as a code block, it usually means the renderer failed or isn’t installed in that environment.
For hosted md2docx.app, try simplifying the diagram and retrying. Extremely large diagrams may hit resource limits.
Prefer breaking complex diagrams into multiple smaller diagrams so text remains readable in Word.

Double-check the fence label

md2docx looks for the language identifier on the fenced block (```graphviz or ```plantuml). If the label is missing (or if the block is fenced as ```text), the converter will treat it as a normal code block.

Diagrams Beyond Mermaid: Graphviz and PlantUML