Markdown to PDF

Markdown is a plain-text format with a small, well-defined core: headings, bold and italic, lists, links, block quotes, code blocks, and horizontal rules. All of that converts to PDF reliably, because there is one obvious way to render each.

The complications sit outside that core. Tables, footnotes, task lists, and strikethrough are extensions rather than original Markdown, and while most are widely supported, a document relying on an unusual one may render as literal text. Raw HTML embedded in Markdown is handled inconsistently. And anything the renderer has to fetch — an image referenced by a relative path, a remote diagram — will be missing from the PDF unless the path resolves. Use absolute image URLs, or check the output specifically for missing images.

Markdown has no concept of a page, which is the root of most layout surprises. A heading can land at the bottom of a page with its section starting overleaf, and a long code block can split awkwardly across a boundary. There is no Markdown syntax for a forced page break; where the renderer supports raw HTML, a div with a page-break style is the usual workaround.

Code blocks are worth attention because they do not wrap the way prose does. A line of code longer than the page width is either truncated or overflows, and both look broken in a printed document. Keep code lines under roughly 80 characters in anything destined for PDF, and prefer fenced blocks with a language tag so syntax highlighting is applied consistently.

The case for writing in Markdown and exporting to PDF is that the source stays plain text: it diffs cleanly in version control, it is readable without special software, and it will open in thirty years. That makes it a strong fit for technical documentation, README files that also need a distributable version, meeting notes, and academic drafts where the content matters more than the typography.

It is the wrong pipeline when layout is the point. Anything with a designed cover page, precise column widths, positioned logos, or a signature block that must land in an exact spot is better authored in a tool that shows you the page. Markdown deliberately gives you no control over where things land, which is a feature while writing and a limitation while designing.