Convert MD to PDF

This is the difference from every other document conversion on the site. A Word file knows its page size, its margins and its fonts; a Markdown file knows none of those, because the format deliberately records structure and leaves appearance to whatever renders it.

So every decision about the page — its size, its margins, the typeface, where a break falls — is made by the converter, and none of them is in your file. That is the trade Markdown makes, and it is usually a good one: the same document becomes a web page, a slide deck and a PDF without being rewritten. The cost turns up here, because a converter that has not been told how to read Markdown has nothing to render and falls back to setting the characters.

Every character of the file arrives on the page, in order, in one typeface. A line reading ## Requirements is set as ## Requirements. A bullet written with a hyphen is a line beginning with a hyphen. A fenced block still carries its three backticks above and below. Bold keeps its four asterisks. Nothing is dropped and nothing is interpreted, because the document engine behind this pair reads text and has never been given a Markdown filter.

What that leaves is worth being precise about. Line breaks, blank lines and indentation are preserved exactly, so a document whose value is its commands and its configuration converts to something usable. A document whose value is its heading hierarchy does not, and the answer there is to render the Markdown in the tool you wrote it in — an editor preview, a static-site build, a documentation pipeline — and print the PDF from that. This conversion is for fixing the text of a file, not for typesetting it.

A Markdown document showing six diagrams contains no diagrams. It contains six paths, and the pictures live beside it on disk or on a server. This surprises people converting for the first time, and it is the commonest reason a PDF arrives with gaps.

The fix is to make the paths resolve before converting. Relative paths have to point at files that actually accompany the document; absolute web addresses depend on that server being reachable. If the images are the point of the document, this is the step to get right rather than the conversion settings.

A great many Markdown files open with a block fenced by three hyphens containing a title, a date and some tags. Static-site generators, documentation builders and note applications read that as metadata and remove it before rendering anything.

This conversion does not know the convention and prints the block like everything else, so the PDF begins with three hyphens and a list of key-value pairs before the document starts. Deleting the block before converting is the whole fix, and it is worth doing on a copy so the original keeps working in whatever tool wrote it.

The original description of Markdown from 2004 was informal, CommonMark is the precise specification most tools follow, and the pipe tables, task lists, footnotes and strikethrough everybody uses are extensions on top of it. Which of those a tool implements is normally the question that decides how a document comes out.

It is not the question on this page. Nothing here implements any of them, or the core either, so a GitHub table and a CommonMark heading are treated identically — as lines of text. That is at least predictable: there is no flavour to guess at and no renderer to test against, and what you see in your editor with syntax highlighting off is what the PDF will contain.

Because the audience is not you. A client, a lawyer, a committee or a compliance officer wants a document they can open, print, sign around and file — not a file their machine offers to open in a code editor, and not a repository they have to navigate. The hashes travel with it, so this is a fixed copy rather than a presentable one.

A PDF also freezes the state. A README changes every week; a PDF of it is what was true on the day it was attached to something, which is exactly what a review, a submission or a contract annex needs. Keep writing in Markdown and export at the moment somebody outside needs a copy.

HTML when the destination is a web page or a documentation site, since Markdown was designed as a shorthand for it and the conversion is closer to a translation than a rendering.

DOCX in one specific and common situation: the recipient will only accept a Word file, and wants to add tracked changes. Markdown has no review workflow at all, so a document going into a round of comments is better handed over as DOCX and read back afterwards — and PDF is for the version that is finished. That target runs through the same engine, so the markup arrives in the Word file as text too; the difference is that the reviewer can fix a heading and you cannot fix one in a PDF.