Markdown to PDF: Why the Simple Conversion Breaks (and How to Get It Right)
Markdown to PDF is sold as a solved problem. Feed the same .md file to pandoc, a VS Code extension and GitHub's print view and you get three visibly different documents, because each uses a different rendering engine, and only one of them is the engine that produced the preview you checked.
PDF internals · · 4 min read
The conversion that should be trivial, and is not
Of all the document conversions, Markdown to PDF looks like the easy one. The format exists precisely because it is trivial to parse, and a PDF is just a printout. Yet it is the conversion where people report the most surprising failures: tables without borders, code blocks that run off the page, checkboxes that vanish, images that disappear.
The root cause is that "Markdown" is several dialects. The tables, task lists and strikethrough that GitHub popularised are GitHub-Flavoured Markdown, not part of the original CommonMark spec. A converter only renders what its parser recognises, and different tools recognise different subsets. Default pandoc, VS Code's Markdown PDF extension, and your editor's built-in preview each apply their own dialect rules, so the same file produces three different documents before you have changed a single line.
What renders reliably, and what silently breaks
Headings, bold, italic, simple lists, links and blockquotes survive everywhere: they are the original CommonMark core, and every serious parser gets them right.
The trouble concentrates in the extensions. Tables are the most common casualty: pandoc renders them but splits wide ones awkwardly across page breaks, while simpler converters drop them to raw pipe characters. Fenced code blocks lose their monospace styling or overflow the page width because no engine line-wraps them by default. Task lists need the GFM extension explicitly enabled in pandoc, otherwise the checkboxes vanish. Footnotes work in pandoc and almost nowhere else. Inline HTML, often the only way to control a layout in Markdown, is dropped by strict parsers entirely.
Concretely, this input:
| Feature | Supported | |---------|-----------| | Tables | yes | - [x] Converted - [ ] Reviewed
comes out of a converter without GFM support as a run of literal pipes and brackets: the table is gone, the checkboxes are gone, and nothing in the output told you either happened.
The failure mode that costs the most time is the silent one. The converter does not tell you it discarded something; the PDF simply arrives without it, and the missing piece is usually the table or the checkbox list the whole document was about.
Why your preview disagrees with your PDF
When the PDF looks wrong, the standard advice is to check the preview. The advice is right and usually useless, because the preview and the PDF were produced by different programs. Your editor previews with its own Markdown parser; the converter parses with another; the PDF writer lays out with a third. A table that renders beautifully in the preview can be flattened in the PDF without any of the three tools being individually broken: they just disagree about what the input means.
The fix is to make the preview and the PDF the same rendering. This site's markdown to PDF converter works that way: the preview you see is the actual HTML document, rendered by the same browser engine that will print it to PDF. There is no separate PDF layout engine to diverge, because the preview is the PDF's source, not an imitation of it. What you check on screen is, by construction, what lands in the file.
The same approach is why the output has no watermark and no page limit. A server-side renderer pays for every document it produces, and the watermark is how the free tier recovers that cost. When your own browser does the rendering, there is no server cost to recover, so there is nothing to cripple the output with.
The same architecture powers the CSV to PDF converter: a live table preview feeds the browser print engine, so the columns you check on screen are the columns that land in the file.
The one trade-off worth knowing
Browser print engines decide page breaks by their own rules, and Markdown has no native way to request them. If a code block or table splits awkwardly, the fix is in the print dialog rather than the source: adjust scale or margins, or switch paper size, and the whole document re-flows. That is a reasonable trade for most documents, but it means precise page control is not part of the deal.
For reference, the same limitation applies in the other direction: see why PDF text extraction fails for what happens when a PDF goes back to Markdown.
When you need something heavier
If you need academic citations, a bibliography, a table of contents, or professional typography such as hyphenation and ligatures, reach for pandoc with a LaTeX engine and a template. That stack exists for exactly that job, and no browser-based converter competes with it there.
For everything else (an AI-generated draft that needs to become a shareable document, internal docs, README printouts, a proposal written in an editor), open the Markdown to PDF converter and try it with a document that has tables and task lists. Those are the two features that expose which engine is really doing the work.