How to share Markdown online without broken formatting

If the recipient only needs to read the result, do not make them open raw Markdown. Send a rendered PDF or document for a fixed handoff, use a shared Markdown workspace to edit together, or publish a web page when you need one public link that can be updated later.

The important choice is not "which Markdown app is best?" It is what the next person needs to do.

The table is about jobs rather than brands. A tool can be excellent at real-time editing and still be the wrong home for a public client deliverable, and a PDF can be ideal evidence of what was approved and frustrating for a document that changes weekly.

Why Markdown changes when it moves

Markdown is not the only format with this problem: a PDF loses the other way round, keeping layout and losing structure, which is the subject of PDF to website.

CommonMark defines Markdown as a plain-text format for structured documents, and the punctuation is source code for a renderer: ## is a heading only after software interprets it, pipes form a table only in a dialect that supports tables, and a fenced block becomes highlighted code only when the destination recognizes its language label.

This compact fixture already contains several assumptions:

## Release plan

| Owner | Status |
| --- | --- |
| Ana | Ready |

```js
console.log("ship")
```

The diagram is in the appendix.[^1]

[^1]: Render the Mermaid source before publication.

The heading and fenced code have a CommonMark baseline. The table belongs to an extension formalized by the GitHub Flavored Markdown specification. GitHub documents footnotes as a platform feature and notes they do not work on every GitHub surface, in its formatting guide.

So "it rendered correctly where I wrote it" is evidence about that editor, not proof about the next destination. A destination that treats the input as plain text leaves the punctuation visible; another parser may keep the basic structure while a table, footnote, task list or diagram does not survive.

Choose the sharing method by the next action

Send the raw file for source review

A .md file is the honest handoff when the source is the deliverable: documentation in a repository, a prompt another agent will continue, a draft someone will edit in a Markdown-aware tool. Keep referenced images with it, or replace relative paths with URLs the recipient can reach.

Do not choose it just because it is the format you have. Someone who only needs to approve the argument should not have to select a parser first.

Export a PDF for a fixed snapshot

PDF is useful when the question is "is this exact version approved?" It freezes layout well enough to review as a page and separates the approved snapshot from later edits. The cost is equally clear: it is no longer the convenient source, and every meaningful update produces another file. Check page breaks, long code lines, links and image resolution in the exported file rather than trusting the editor preview.

Use an ordinary document for familiar review

Convert to a document when comments, suggested edits or an established review process matter more than keeping Markdown as the source. Treat the result as a new artifact: inspect the table, code, lists, links and footnotes, then set its access rules there. No universal "paste Markdown into a document" promise is safe, because the result depends on the destination, the surface inside it, and whether you pasted source, rich text or rendered HTML.

Use a Markdown workspace to edit together

A collaborative workspace keeps the source and its rendered view near each other. HackMD's sharing documentation describes a copyable note URL plus separate read and edit permissions for owners, signed-in users or everyone.

That suits co-authoring, and it makes permissions part of the deliverable. "Anyone with the link," "signed-in users" and a note deliberately published to the web are different states: HackMD's publishing guide says publication makes a note world-readable and documents how its permalinks behave. Check the rules of whichever workspace you choose.

Use a temporary viewer for a quick read

A paste-and-share viewer is the shortest path from source to a rendered link, reasonable for low-stakes material once you have checked what the service stores, who can discover the link, whether it expires and whether you can remove or export the content. Those are product policies rather than Markdown properties: if the answer must still exist next month, "the link works now" is not enough.

Publish a web page for a result that will keep changing

A public page fits when the recipient should open a normal browser link, the presentation matters, and later edits should appear at the same address. It takes one decision up front: the Markdown has to become an actual web page.

Birta makes the publish loop available to a connected agent, but it does not serve a raw .md file as the page. The agent creates valid static HTML with a root index.html and publishes it when the conversion is done — or shows you the draft preview first and waits, if the prompt asks it to. The generic file and folder rules live in the HTML hosting guide, and if the Markdown is one item in a folder of drafts and images, the guide to publishing a whole folder covers what survives the trip.

One situation changes the decision rather than the mechanics: if the document's real home is a workspace you keep editing, a converted copy stops matching the source the first time you touch it. Where that leaves a Notion page is a different question.

Publish the Markdown through the same agent

The connected-agent flow removes the download, conversion-site, and upload handoffs. It does not remove review.

1. Step 1InspectIdentify the dialect, assets, tables, code, footnotes, raw HTML, and diagrams.
2. Step 2ConvertCreate accessible static HTML and write the public result as index.html.
3. Step 3PreviewOpen the draft link and check the actual rendered page before it is live.
4. Step 4PublishSay go — the prompt below asks the agent to wait for it — then keep the project address for later edits.

This prompt gives the agent the important boundaries without prescribing a particular visual design:

Use Birta to turn the Markdown below into a public web page.

Treat the Markdown as source. Do not publish a raw .md file. Create a valid,
responsive static page with index.html and any necessary local assets.

Preserve the document hierarchy, tables, fenced code, links, images, and
footnotes. For every unsupported or ambiguous feature, tell me what fallback
you used. For Mermaid, either render an accessible SVG or include a deliberate
Mermaid runtime and a readable fallback; never silently drop the diagram.

Create or select the Birta project, write the draft files, and return its preview
link. Stop there so I can review it. Publish that draft only after I approve it.

[Paste the Markdown here]

If you have not connected an agent yet, the MCP explainer covers what the connection does. The operational rule here is simpler: draft first, inspect the link, then publish.

Check the parts most likely to break

Use a small fixture containing the features your document depends on, run it through the actual method, and open the result the way the recipient will. A practical compatibility check, not a claim about every application or future version.

• Headings and lists: confirm the hierarchy is visible and nested items did not flatten.
• Tables: check every column at narrow widths. Tables are a GFM extension, and long cells may need a responsive wrapper.
• Fenced code: confirm indentation and characters survived. Syntax colouring is optional; readable, copyable code is not.
• Links: open them. Relative links and local image paths that worked beside the source may have no public target.
• Images: verify the recipient can fetch them without your disk, session or private workspace. Keep useful alternative text.
• Footnotes: follow the reference and return link in the rendered result rather than inferring support from one editor.
• Raw HTML: decide whether to preserve, sanitize or replace it. Destinations make their own security decision.
• Mermaid: look for a diagram, not only a code fence. GitHub renders a mermaid fence on supported surfaces per its diagram documentation, and that behaviour does not travel with the text.

For a standalone page, Mermaid's usage documentation shows the page must load and initialize the renderer. Pre-rendering a diagram to accessible SVG avoids that runtime dependency, and keeping visible source or a text summary provides a fallback. If the page does run Mermaid in the browser, keep its security model deliberate, since Mermaid documents strict as the default level.

Choose for the next edit, not only today's send

The fastest handoff today can create the most work tomorrow. Before choosing, ask three questions:

1. Will the recipient edit the source, comment on a snapshot, or only read it?
2. Should the same address show the next approved version?
3. Is the result public, permissioned inside a workspace, or private enough that it should not be uploaded to a sharing service at all?

Choose a file or PDF when each version should stay a separate artifact. Choose a collaborative workspace when permissions and joint editing are the job. Choose a published project when the deliverable is a public page and the same link should keep working after corrections.

If the next question is whether that page received a visit, use the guide to interpreting a shared link's signals before treating a click as proof that someone read it.

On Birta, later publications update the project behind its existing address. The rollback list holds the ten newest published versions, which is a recovery window rather than unlimited history. For the edit-and-restore loop, see how to change a live page without regenerating it.

If the address is part of the deliverable, the same project can use a verified custom domain while its standard address stays available, and the custom-domain guide owns the DNS steps. Neither a stable address nor a custom domain fixes a bad conversion, which is why the preview check comes first.