You finish the design doc on a Friday. It sits in the repo with three Mermaid diagrams in it, and the GitHub preview draws them fine. Monday, your client asks for a copy. Or the bank's architecture board wants it two days before the review, or a compliance reviewer needs one for her file, and none of them can reach your org on GitHub.

So you do the usual thing. You open the preview, crop a screenshot of each diagram, paste the images into a Google Doc, retype the headings so the formatting matches, and export to PDF. Twenty minutes to ship a document you had already written.

Fuzzy boxes in the printed deck

Your monitor shows around 96 pixels per inch. A printer lays down 300 or more. Drop a 900-pixel-wide screenshot into a page that prints at 6.5 inches of usable width and the printer stretches each of your captured pixels across three of its own. Box borders go soft. The 11pt labels inside your nodes turn into grey smears where letters used to be.

You will not catch this on your laptop. You catch it when your client prints the deck for the room, and the one page they all lean in to read is the architecture diagram, and it looks like someone faxed it twice.

The reviewer cannot search a picture of text

Mermaid writes real text into the SVG it draws. Payment Service, retry with backoff, Ledger. Screenshot the diagram and you throw all of that away and keep the pixels.

The compliance reviewer who wants to find every place your system touches the ledger now reads fourteen pages by eye. She cannot hit Ctrl-F. She cannot copy a node label into the finding she is writing about you, so she retypes it, gets one word wrong, and you spend an email thread correcting a mistake you handed her. Someone reading with a screen reader hears silence where your diagram sits.

You will forget to retake it

You change one arrow in the Mermaid source, commit, and move on. The PNG in the Google Doc still shows last month's topology.

You do not re-export on purpose. You re-export the week someone in a meeting points out that the drawing contradicts the paragraph beside it, and by then your client has been quoting the old routing in their own slides for six weeks. Open any document with pasted screenshots in it and you cannot tell which of them still match the source without checking each one against the repo by hand.

Then comes the message you already know: "can you send the editable version?" They are asking for the source. You sent them a photograph of the source, which is why they had to ask.

Render it instead of photographing it

Mermaid already gives you vector SVG in the browser. Each box, arrow and glyph is a set of coordinates rather than a grid of pixels, so a printer solves the geometry at its own resolution instead of blowing up yours. Print the same diagram on an office laser printer or a plotter and the edges stay sharp on both.

Take a diagram like this one, which I keep in the payments doc I send to auditors:

flowchart LR
    Client[Client app] -->|POST /charge| API[Payments API]
    API --> Ledger[(Ledger DB)]
    API -->|on failure| Queue[Retry queue]
    Queue -->|backoff| API
    API -->|webhook| Client

Push that through a real PDF renderer and your reader can select Retry queue, search the file for Ledger, and paste POST /charge into Slack without retyping it. The file comes out smaller than the screenshot version, because a few hundred path coordinates cost less than a bitmap of the same picture. Change the arrow, export again, and the copy on the reviewer's desk matches the copy in the repo, because you generated it from the repo thirty seconds ago.

Your file then goes through the parts of the process you do not control. Your client drops it into a shared drive and prints it double-sided at A4. A reviewer opens the same file at 400% on a 27-inch monitor to read one label. Vector art holds up under both of those. A pasted screenshot gives up at the printer.

How I handle it now

I wrote Markdown With Diagrams to skip the Google Docs detour. You paste your markdown into the left pane, the right pane renders it with your mermaid fenced blocks drawn as SVG in a light card, and Export PDF hands you an A4 file with 1in margins where the text stays selectable and the diagrams stay vector. It reads GitHub-flavored markdown, so your tables, task lists and fenced code with syntax highlighting come out looking like they do in the repo. There is no account to create and the app keeps nothing on a server, which matters when the doc you are exporting describes how money moves through your system.

Next time the reviewer asks for the doc, send her the PDF and the markdown file in the same email. She can read one and diff the other.