Markdown to Word with Mermaid

Fenced mermaid blocks are rendered to crisp vector diagrams and embedded in the .docx, sized to the page. No screenshots, no blurry PNG exports.

Pro · preview is free

Release pipeline

Every commit follows the same path before it reaches production.

Figure 1: Release pipeline

The diagram above is inserted as a scalable image with a caption.

Font Size Paper

Converted in your browser. Your file never leaves your device.

1

Paste Markdown with a Mermaid block

Any fenced block tagged mermaid is detected: flowcharts, sequence, class, state, ER, Gantt, pie and more.

2

See the rendered diagram

The preview draws the diagram at the width it will have on the page, so you can spot overflow before downloading.

3

Download a .docx with vectors inside

Diagrams are embedded as SVG for sharp output in current desktop versions of Word.

Markdown to Word with Mermaid support: how the diagram ends up in the file

Word has no idea what Mermaid is. If you paste Markdown containing a ```mermaid block into Word, you get the source text in a monospace font, which is exactly what most online converters also produce. The only way a diagram can exist inside a .docx is as an image, so the real question is what kind of image, how big, and where.

MDtoDOCX runs the Mermaid renderer in your browser, the same library that draws diagrams on GitHub and in Obsidian. The output is an SVG: a set of paths, rectangles and text nodes rather than pixels. That SVG is written into word/media/ inside the .docx, referenced from a drawing element in the document, and rendered by Word as a vector graphic. Since Office 2016 and in every Word 365 build, Word draws SVG natively through the asvg:svgBlip extension, so lines stay sharp when you zoom to 400% or print on a large-format plotter.

Compatibility with older document viewers

The current exporter targets desktop versions of Word that support SVG. Older Word releases and some third-party or mobile viewers may not display the diagram correctly, so check the final file in the application your reader will use. A full-resolution raster fallback is still on the product roadmap.

Sizing, placement and captions

The rendered diagram carries its natural width and height. We scale it to fit the printable width of the page you chose, which is the paper width minus the margins, and never scale it up beyond its natural size, because a small pie chart stretched to full width looks amateurish. The image sits in its own centred paragraph. Add title="Release pipeline" or caption="Release pipeline" after the opening Mermaid fence to place that text in a Word Caption-styled paragraph below the image.

Supported diagram types

Flowchart, sequence diagram, class diagram, state diagram, entity relationship, user journey, Gantt, pie, quadrant, requirement, gitGraph, mindmap and timeline all render. The renderer uses Mermaid's neutral theme with the diagram font set to match your body font choice, so a Calibri document does not suddenly contain a diagram in a web font. A syntax error in the diagram is shown in the preview at the exact block, and the block is exported as a highlighted code paragraph rather than failing the whole conversion.

Editing after export

Be clear about the trade-off: the diagram in Word is a picture. You can move, resize, crop and wrap text around it, but you cannot drag a node to a new position. Keep the Mermaid source in your Markdown and re-export when it changes. On request we also write the source into the image's alt text, so a reviewer using a screen reader hears the structure and you can recover the source from the .docx alone.

Free versus Pro

Diagrams are rendered as vector images embedded in the document. Free users get the rendered preview and a download in which the Mermaid block appears as a code paragraph; Pro unlocks the embedded diagrams. The identical renderer powers Markdown to PDF with Mermaid. Documents that mix diagrams with math benefit from the LaTeX to Word equations path, and pipe tables next to your diagram come through as real Word tables.

Mermaid diagrams in Word: MDtoDOCX vs Pandoc vs copy-paste

Diagram handling	MDtoDOCX	Pandoc	Copy into Word
Mermaid block becomes	Embedded SVG	Code block, unless a filter is installed	Plain text
Setup	None	Node.js, mermaid-filter, headless Chrome	None
Resolution	Vector, sharp at any zoom	PNG at fixed DPI	n/a
Fits the page width	Yes, automatic	Often oversized, needs manual resize	n/a
Caption	From the fence title or caption metadata	Manual or pandoc-crossref	Manual
Preview before export	Yes	No	n/a
Syntax error handling	Highlighted in preview, block kept as code	Filter aborts conversion	n/a

Frequently asked questions

Can Word display Mermaid diagrams?

Not from source. Word has no Mermaid renderer, so the diagram must be converted to an image first. MDtoDOCX renders it to SVG in your browser and embeds that image in the .docx.

Will the diagram be blurry when I print?

Current desktop versions of Word render the embedded SVG as a vector, so it stays sharp when resized or printed. Older and third-party viewers may not display it correctly yet.

Which Mermaid diagram types are supported?

Flowchart, sequence, class, state, ER, user journey, Gantt, pie, quadrant, requirement, gitGraph, mindmap and timeline. Anything the current Mermaid release renders will export.

Can I edit the diagram inside Word?

You can resize, move and crop it like any picture, but not edit nodes. Keep the Mermaid source in your Markdown and re-export. Optionally the source is stored in the image alt text.

How is the diagram sized?

It is scaled down to fit the printable width of your chosen paper size and never scaled up beyond its natural size. It is centred in its own paragraph.

What happens if my Mermaid has a syntax error?

The preview marks the block with the error message. The rest of the document converts normally and the block is exported as a code paragraph so nothing is lost.

Do I get a figure caption?

Yes. Add a title or caption value to the Mermaid code fence metadata and MDtoDOCX places it in a Word Caption-styled paragraph. Automatic figure numbering is not included yet.

Is Mermaid rendering free?

The preview is free. Downloading a .docx with the diagram embedded requires Pro, which starts at $4.9 for a 7-day pass. Free downloads keep the Mermaid source as a code block.

Does the diagram get uploaded to render?

No. Mermaid runs inside your browser tab. The source, the SVG and the finished .docx never leave your machine.