Markdown exists so writing does not stop
The point of Markdown is that structure is typed rather than clicked. A hash makes a heading, a hyphen makes a list item, asterisks make something bold, and none of it requires leaving the keyboard or waiting for a toolbar. That is why notes, documentation and half the internet's drafts are written in it.
The awkward moment comes at the end, when somebody who does not use Markdown needs to read the result. They want a document, not a text file full of punctuation, and a PDF is the usual answer.
Your browser writes the file
The Markdown is rendered to a formatted page, that page opens in a new tab, and your browser's print dialogue appears. Choosing Save as PDF as the destination produces the file. Nothing is uploaded and nothing downloads on its own.
Two of the dialogue's defaults are set for printing web pages rather than making documents, and both want changing. Turn off headers and footers, or every page carries a URL and a timestamp. Check the paper size, which follows your system locale and may not match wherever the document is going. A third is worth knowing about: background graphics is off by default, and with it off, table heading shading and code block backgrounds print as plain white.
Know which Markdown you are writing
Markdown has no single specification. Every renderer supports a different set of extensions, which is why a document that looks right in one editor comes out wrong somewhere else. Knowing which dialect you are writing to is not pedantry; it is the difference between a clean document and a page of stray punctuation.
The [msm_tool slug="markdown-to-pdf"] renders CommonMark, plus the pipe tables and strikethrough that GitHub added. In practice that covers everything most people write: headings to six levels, bulleted and numbered lists including nested ones, tables, fenced and inline code, block quotes, links, images, bold, italics and horizontal rules.
What falls outside it is the layer of extensions that particular tools invented — footnotes, definition lists, admonition blocks, and the YAML front matter that static site generators put at the top of a file. Those render as ordinary text rather than disappearing, which is the honest failure mode: you can see what did not convert instead of wondering what happened to it.
Raw HTML, and why it is cleaned first
Markdown permits HTML inside it, and always has. That is part of the specification rather than a quirk, and it is how people get a table or a footnote into a document whose renderer lacks them.
It also means a Markdown file can carry a script. When that file is rendered and handed to a print window, the script runs, and the file you pasted may have come from a repository you have never read. So the rendered output is stripped first: script and frame elements removed, event handler attributes removed, and addresses that are not ordinary web or mail links dropped. Formatting HTML survives untouched. This costs you nothing you wanted and removes something you did not ask for.
Writing so it prints well
- Give tables room. A wide pipe table is cramped on portrait A4. Switch to landscape in the print dialogue rather than reducing the scale, which shrinks everything else with it.
- Keep code lines short. A fenced block wider than the page is wrapped rather than clipped, so nothing is lost, but the line breaks fall wherever the page ends rather than where you put them.
- Use full addresses for images. A relative path has nothing to resolve against once the page is built from your text alone, so the image simply will not appear.
- Write links out where it matters. They stay clickable in most PDF readers and are invisible on paper, so a document meant to be printed should carry the address in the text.
What the page breaks do, and do not, respect
Where a page ends is decided by the print engine, not by you. Three rules are set on your behalf, because they are the ones that make printed documents look broken when they are missing: table rows and images are kept whole rather than split down the middle, a table's heading row repeats at the top of every page it runs onto, and a heading is not left stranded at the foot of a page with its section overleaf.
Beyond that you have no control. You cannot force a section onto a fresh page, and on a long structured document a break will eventually fall somewhere awkward. A few pages is comfortable; a fifty-page manual wants a tool that understands pagination.
Check the preview, not the source
The print dialogue's preview panel shows exactly what the file will contain, and it is where an unconverted extension becomes visible — a footnote marker sitting as a bracketed number, a block of front matter across the top of page one.
Read it as a reader rather than as the author. You know what the source said; the person receiving the PDF only sees what came out.