Convert Markdown to PDF

Which Markdown, and what it becomes

Markdown is a family rather than a single specification. The common core — headings, emphasis, lists, links, images, block quotes, code blocks — is the same everywhere, and beyond that every implementation differs. What is supported here is the widely-agreed extended set: tables, fenced code blocks with syntax highlighting, task lists, strikethrough, footnotes and front matter. That covers what almost everyone writes, and it is worth knowing the boundary rather than discovering it.

Headings become real PDF structure rather than just larger text: they carry outline levels, so the PDF gets a bookmark sidebar you can navigate. Links become working link annotations. Code blocks are set in a monospaced face with highlighting, which is the difference between a document that is pleasant to read and a wall of grey. Page size and margins are chosen for reading rather than inherited, since a Markdown file has no opinion about paper.

Images have to be reachable, and this is the most common disappointment. A Markdown file references pictures rather than containing them, so a relative path only resolves if the image is dropped in alongside the file, and a web address only resolves if that server allows other sites to fetch it. A picture that cannot be found is labelled in the PDF rather than leaving a silent gap, so a missing diagram is visible rather than something you notice after sending the document.

Two things are deliberately shown as code rather than rendered. Math formulas in LaTeX notation and Mermaid diagrams each need their own renderer, and rendering them incorrectly is worse than showing the source — a misrendered equation is wrong in a way nobody can see. Raw HTML inside the Markdown is handled for simple inline formatting and not for layout, since an arbitrary block of markup has no place in a paginated document.

When you want something else

Pandoc is the serious tool for this and it is free. pandoc doc.md -o doc.pdf --pdf-engine=xelatex typesets through LaTeX, which produces genuinely beautiful output with proper hyphenation, widow control and a real table of contents — and with a template you control every aspect of the design. It also renders LaTeX math correctly, which is the specific gap here. The cost is installing a TeX distribution, which is not small.

For documentation rather than a one-off document, a static site generator or mdBook produces something better than a PDF: searchable, linkable, and readable on a phone. Convert to PDF when the document has to be printed, attached or archived — and keep the Markdown as the source of truth either way, because it is the version that can be edited and diffed.