Embedding Mermaid Diagrams in Word

Technical documentation often requires diagrams: flowcharts, sequence diagrams, or Gantt charts. Traditionally, you would draw these in a tool like Visio or Lucidchart, export an image, and paste it into Word. If the diagram changed, you had to repeat the whole process.

Diagrams as Code solves this. You write the diagram description in text, and the renderer draws it. md2docx supports Mermaid.js natively, meaning you can include diagrams directly in your Markdown and get high-quality images in your DOCX file.

How It Works

To include a diagram, use a fenced code block with the language identifier mermaid.

```mermaid
graph TD;
    Start --> Process;
    Process --> Decision;
    Decision -- Yes --> End;
    Decision -- No --> Process;
```

When you convert this file, md2docx detects the Mermaid block, renders it to a high-resolution PNG image on the server, and embeds that image into the Word document.

Supported Diagram Types

We support most standard Mermaid diagram types:

• Flowcharts: graph TD or flowchart LR
• Sequence Diagrams: sequenceDiagram
• Class Diagrams: classDiagram
• State Diagrams: stateDiagram-v2
• Gantt Charts: gantt
• Entity Relationship: erDiagram

Best Practices for Word Output

1. Keep it Simple

Word pages have limited width (usually 8.5 inches). Huge diagrams with dozens of nodes will be scaled down to fit the page, which might make the text unreadable. Try to break large diagrams into smaller sub-processes.

2. Orientation

For flowcharts, Top-Down (TD) usually fits a portrait Word document better than Left-Right (LR), which can get very wide very quickly.

3. Styling

The diagrams are rendered using a neutral theme that looks good in professional documents. Custom styling inside the Mermaid block is supported but can be tricky; sticking to the defaults ensures the most consistent results.

A sequence diagram example

Sequence diagrams are a great fit for Word because they read vertically. Here’s a simple example you can paste into a report:

```mermaid
sequenceDiagram
  participant User
  participant Web
  participant API
  User->>Web: Submit request
  Web->>API: POST /convert
  API-->>Web: DOCX download
  Web-->>User: Save file
```

If your diagram has many participants, shorten labels and split the flow into phases (for example: “Auth”, “Conversion”, “Download”) so it stays readable on a page.

Debugging Mermaid blocks

If a diagram fails to render or looks wrong, the fastest debugging loop is:

1. Verify the fence label is exactly ```mermaid.
2. Paste the block into the Mermaid Live Editor to confirm syntax.
3. Simplify: remove styling and reduce node count until it renders.
4. Convert again and iterate.

A surprisingly common issue is an unclosed code fence (missing the ending ```). That can cause the rest of the document to be treated as part of the diagram block.

Making diagrams readable in Word

• Prefer multiple small diagrams over a single mega-diagram.
• Keep node labels short and explain details in the surrounding text.
• Avoid ultra-wide layouts unless you plan to use a landscape section.
• If you need landscape pages for wide figures, use section breaks and layout options (see Advanced conversion options).

Diagrams are most useful when they’re paired with a short caption or paragraph describing what the reader should learn from the figure. Treat each diagram as a “chart” in your narrative, not just decoration.

Common mistakes (and quick fixes)

• Wrong fence label: the block must start with ```mermaid (not ```md or ```text).
• Copy/paste artifacts: AI tools sometimes include “```” inside the diagram body. Remove stray fences so Mermaid can parse correctly.
• Overly complex diagrams: if text becomes unreadable, split the diagram into two smaller diagrams and place them under separate headings.