Markdown to PDF

Markdown is a writing format, deliberately close to plain text: readable in any editor, diffable in version control, and free of the invisible state that makes word processor files awkward to collaborate on. What it is not is a delivery format. A .md file handed to someone outside the habit is a text file full of hashes and asterisks.

PDF is the complement. It fixes the appearance, paginates the content, opens on anything without an editor or a renderer, and prints properly. Writing in Markdown and delivering in PDF gets both halves: a source you can keep in a repository and review as text, and an artefact anyone can read.

The typical cases are documentation handed to a client, a README turned into a printable reference, technical notes for a meeting, and academic or personal writing drafted in plain text and submitted as a document.

There are two ways to make a PDF from Markdown and they produce very different files. The shortcut is to render the Markdown as a web page and photograph it, which is quick and yields a document made of pictures — unsearchable, uncopyable, invisible to screen readers, and fuzzy when printed at anything other than the size it was captured.

The other way lays the content out on a real page: text drawn from embedded fonts at chosen sizes, paragraphs flowed to a measure, page breaks placed between blocks rather than through them. That is what happens here, and it is why the output behaves like a document rather than a slideshow of images.

The difference shows up in the ordinary things people do with PDFs afterwards. Searching for a term works. Copying a code snippet out gives you code. Printing at A4 from a document laid out for A4 produces crisp type at any zoom.

Headings become a genuine size hierarchy rather than bold text, so the document has visible structure. Emphasis renders as italic and bold. Ordered and unordered lists nest properly, with indentation that makes the levels legible. Blockquotes are set off from the body, and horizontal rules become rules.

Code gets the most careful treatment because it is the least forgiving. Inline code is set in a monospaced face so it reads as code mid-sentence; fenced blocks keep their whitespace exactly and are not reflowed, since indentation is meaningful in most languages. The one thing to check on a printed listing is line width, because a page cannot scroll sideways.

Tables render with aligned columns and real cell boundaries. Links keep their text and remain visible as links. Images referenced in the source are placed inline at a size that fits the page.

A few habits improve the output more than any setting. Use one top-level heading and nest consistently beneath it — a document that jumps from a first-level heading to a third-level one produces a hierarchy that looks broken on a page even though it renders fine in a browser.

Keep code lines under about eighty characters where the listing matters, because that is roughly what fits comfortably on a portrait page in a monospaced face. Long tables are worth splitting into two narrower ones rather than letting the columns compress.

For documents that need maths, diagrams or a live preview while writing, the Markdown Editor is the better starting point — it renders LaTeX and Mermaid, autosaves, and exports to PDF, Word and HTML. Markdown to Word is the route when the recipient needs to edit rather than read.