Send the raw file and they see asterisks. Export to PDF and you lose easy revisions. The third option — and how to pick between the three by what the document has to do next.
You wrote something in markdown — notes, a report, a spec, or something an assistant handed you — and now it has to reach a person who does not live in a text editor. You send the file. They open it and see this:
## Q3 summary
The **churn** figure excludes accounts that [never activated](/notes).
Nothing is broken. That is exactly what a .md file contains. Markdown is plain text plus a convention: ## means a heading, ** means bold, []() means a link. Something has to read those marks and draw the document. Editors do it, browsers with an extension do it, hosting services do it. A default text editor and most mail previews do not — so they show the marks.
Which leaves you with a small decision that is worth making deliberately, because the three routes fail in different places.
Fine when the person already has something that renders markdown, and better than fine when they might edit it and send it back — because the file stays the source, with no conversion in either direction to lose things.
Where it goes wrong is that you cannot see their setup from your end. "Just open it in your editor" is an instruction that assumes an editor. If you are wrong, they either see the asterisks or they quietly do not read it at all, and the second failure is invisible to you.
The reflex, and genuinely right when the document is done. A signed proposal, something to be printed, something that goes into a records system — those want a fixed artefact, and PDF is what fixed artefacts look like.
Two costs, one obvious and one not.
The obvious one: conversion is lossy in the places markdown is strongest. Links can flatten into unclickable text, diagrams that were rendered from source often do not survive, and a wide table becomes something that either shrinks or spills off the page. Pandoc handles a lot of this well, but it is a pipeline you now own and re-run on every change.
The quiet one: an export is a copy, and copies do not know they are out of date. You revise, you re-export, you send again. Meanwhile the version you sent on Tuesday is still sitting in their downloads folder looking perfectly authoritative. Nobody gets an error. They just read the old numbers. That is the same failure mode as replacing a file that is already published, and it is worse here because you deliberately created the copy.
If the file has just arrived and you only need to read it, drop it into the MD viewer — it renders headings, tables, lists and code locally in your browser, with nothing uploaded and nothing to install.
Render the markdown once, put the result at a stable URL, and send the URL.
What that changes:
The trade is that a link is not an archive. If someone needs a frozen artefact for a records system, that is a PDF, and no amount of convenience changes it.
There is also a control worth being deliberate about: a page at an address has an audience, and the default is not always the one you want. A draft going to one reviewer should be at an unguessable, unindexed address rather than a findable one. That is a separate dial from the format — see private link versus public deploy for where each end fits.
One question: what does this document have to do next?
| It has to be… | Send | Because |
|---|---|---|
| edited and sent back | the raw .md | The file is the source; conversion in both directions loses things |
| filed, printed, signed | a PDF | A fixed artefact is the actual requirement, not a workaround |
| read, and it will change again | a link | Formatting survives, nothing to install, and revisions land in place |
Most of the confusion here comes from treating the third case as the second one. A document that is still moving does not want to be frozen; it wants an address. Sending a file was never the goal — the format only has to survive the handoff, and which format does that depends entirely on what happens after it lands.
One more thing, because it is the part people skip: check what they actually see. Open your own link in a private window, or on a phone, before you decide the handoff worked. The gap between "I sent it" and "they read it" is where most of these failures live, and it is a thirty-second check.
Replacing a page you have already handed someone is a different problem from publishing it the first time. Why the usual answer is 'learn git', who that answer is actually for, and what the other routes really cost.
Client-side encryption tools turn your page into an encrypted file, so the protection and the artifact are the same object — every edit means re-running the tool and re-uploading. What that actually costs, the salt setting that decides whether your old share links survive, and when a hosted password is the better trade.
Running the studio out of one folder per client is a good structure for making the work. It stops at the point where the client has to open it — a private repo needs a GitHub account, and Pages built from one is public by default. What the handover step actually needs, and how to add it without breaking the folder.
miinideck turns a single HTML file into an unguessable link with optional password and expiry. Default-private, never indexed.