TL;DR — Mermaid is a great way to keep diagrams
close to the Markdown that explains them. The hard part is export. If the PDF
or DOCX path treats the diagram as an afterthought, the result gets blurry,
cramped, or inconsistent. depapel
already supports Mermaid in Markdown export, with one important honest caveat:
PDF and DOCX currently embed Mermaid as raster images, not native SVG.
Mermaid is attractive for the same reason Markdown is attractive: it keeps the
source editable, portable, and easy to version.
Instead of drawing a flowchart in a separate tool and attaching an image, you
can keep the diagram in the same Markdown file as the README, design doc, runbook,
or architecture note. That is a much better authoring story.
But the real test is not authoring. The real test is export.
Why diagram export is harder than on-screen preview
On-screen preview can hide a lot of weaknesses:
- the diagram has flexible width,
- the browser can scale it freely,
- and you can zoom if labels feel cramped.
A PDF or DOCX is less forgiving. The diagram has to survive:
- page width,
- print density,
- surrounding text,
- and the fact that the reader may never zoom in.
So a Mermaid export path has to answer a few practical questions:
- Is the text still readable?
- Does the diagram fit the page?
- Does it stay visually consistent in both PDF and DOCX?
- Does the surrounding content still flow like a document?
That is where many workflows become messy.
The common bad workflow
Without a real Markdown-to-document path, teams often fall back to one of these:
- take a screenshot of the diagram,
- export from a separate diagram tool,
- paste the image into Word manually,
- or print a browser preview and accept whatever comes out.
All of those break the "Markdown as source of truth" idea.
Now the diagram and the text can drift apart. Editing gets slower. Review gets
harder. And the document stops being reproducible from one source file.
Why Mermaid belongs in the same source document
Keeping Mermaid inside Markdown has real advantages:
- the diagram changes in the same commit as the text,
- architecture notes stay close to the actual system explanation,
- AI-assisted drafting can produce the first version in one file,
- and the export path can stay deterministic.
For technical docs, that is a real product win. A README, handoff doc, or RFC is
much easier to maintain when the text and diagram live together.
A simple example
Here is the raw Markdown for the kind of Mermaid block that shows up in real
docs:
```mermaid
flowchart LR
Draft[Markdown draft] --> Review[Review in depapel]
Review --> PDF[PDF export]
Review --> DOCX[DOCX export]
```
That is readable in source form and easy to change. The export question is
whether the final document still keeps that clarity.
What you want from Mermaid export
For PDF and DOCX, the bar should be practical rather than magical.
You want:
- readable labels,
- stable layout,
- enough resolution that the diagram does not feel soft,
- and a document flow where the diagram still belongs to the section around it.
You do not necessarily need every diagram to stay as a perfect vector object
inside every output format. But you do need it to remain useful once the file is
shared.
Where depapel fits
depapel already supports Mermaid as part of the Markdown conversion workflow.
That matters because it means the diagram is part of the same document pipeline
as the text, not a separate manual step.
Product-backed facts in this repo today:
- Mermaid is rendered in-process through Poseidon.
- The PDF and DOCX outputs include Mermaid-rendered diagrams.
- PDF and DOCX currently embed those diagrams as PNG, not direct SVG.
- Diagram density is tuned intentionally because width matters for readability.
That last point is important. For exported documents, width and density are not
just implementation trivia. They are what determines whether a diagram feels
usable on the page.
Honest limitations
This is where the content should stay precise.
depapel should claim:
- Mermaid works in the Markdown export workflow.
- PDF and DOCX include the rendered diagram.
- The current PDF/DOCX path is raster-image oriented.
depapel should not claim:
- native SVG embedding in PDF or DOCX,
- unlimited readability for arbitrarily large diagrams,
- or that huge architecture maps will always look great on one page.
If a Mermaid diagram is too large or too dense, you still need to simplify it,
split it, or give it more space in the document.
Practical advice for better Mermaid documents
If you want Mermaid to export well, a few habits help a lot:
- Keep node labels short.
- Prefer two smaller diagrams over one massive one.
- Put the diagram near the heading and explanation that introduce it.
- Avoid trying to fit a whole system map into a single page-sized export.
- Export once and inspect the actual PDF or DOCX instead of trusting preview
alone.
These are not depapel-specific rules. They are just good document-design rules.
Where this is especially useful
Mermaid in PDF or DOCX is especially useful for:
- architecture notes,
- AI-generated handoff docs,
- internal runbooks,
- README exports,
- and technical proposals that need one or two clear flow diagrams.
In all of those cases, the diagram is there to support reading, not to become a
full design canvas.
Final take
Mermaid is one of the best reasons to keep technical docs in Markdown. The text,
structure, and diagram can evolve together.
The export path is what decides whether that promise survives contact with the
real world.
If you want a Markdown-first workflow that can still produce a shareable PDF or
DOCX with Mermaid included, depapel is already a credible fit. Just keep the
expectation honest: it is a strong Markdown-to-document path for practical
diagrams, not a claim that every complex diagram becomes perfect vector output
in every office format.
Please enable JavaScript to use depapel.