How to Turn Markdown into a Beautiful PDF (Developer's Guide)

Every developer I know writes in Markdown. READMEs, notes, design docs, changelogs, half of a personal resume — it all lives in .md because it's fast, diffable, and lives in plain text next to the code. The problem arrives the moment someone asks you to "send it as a PDF." Markdown renders beautifully on GitHub; turned into a PDF by the wrong tool, it becomes a wall of monospace text with no code colors, broken tables, and ugly margins. This guide is the route I settled on after fighting Pandoc, online converters, and browser prints for years.

Why developers love Markdown

It's worth being explicit about the appeal. Markdown is plain text, so it's small, searchable, and version-controlled with the same Git you already use. You can write it in any editor on any machine, and it has zero lock-in. The trade-off is that plain text isn't a fixed-layout document — to hand it to a non-developer, print it, or attach it to an application, you need to render it into something like PDF.

The three routes from Markdown to PDF

There are three real paths, and I've used all of them:

Route 1: Pandoc (power users, CLI)

Pandoc is the Swiss Army knife of document conversion. A command like the one below converts a Markdown file to PDF with code highlighting:

pandoc resume.md -o resume.pdf --highlight-style=github -V geometry:margin=2cm

It's scriptable and powerful — you can template the whole thing. The catch: it needs a LaTeX engine installed to produce PDFs, which is a heavy, fragile setup on Windows, and tweaking typography is a rabbit hole. Great if you already live in a terminal; overkill if you just need one PDF.

Route 2: Online converters (convenience, privacy trade-off)

There are web services that paste Markdown and spit out a PDF. They're fast, but your document is uploaded to their servers — which is a non-starter for internal docs, client proposals, or a resume with your personal details. They also cap features on free tiers.

Route 3: In-browser rendering (the middle path)

This is where I landed. A browser-based renderer parses Markdown to HTML with marked, applies a clean stylesheet (I use the GitHub look), highlights code with highlight.js, and prints the rendered HTML to PDF locally. No install, no upload, live preview as you type. Our Markdown to PDF tool does exactly this: write on the left, see the styled result on the right, pick GitHub / light / dark theme, and download.

Route	Setup	Privacy	Code highlight	Best for
Pandoc + LaTeX	Heavy install	Local, fully private	Yes, customizable	Scripts, CI, bulk docs
Online converter	None	Uploaded to server	Usually basic	One-off public notes
Browser renderer	None	Local, private	Yes, highlight.js	Resumes, docs, quick exports

Code highlighting and tables: the two make-or-break features

A Markdown PDF that can't do these two things looks amateur. Code blocks should be syntax-highlighted with a dark background and readable contrast — unhighlighted code in a PDF is nearly impossible to scan. Tables need real borders and column alignment, not a raw pipe-dump. A good renderer uses highlight.js for fenced code blocks (```python ... ```) and renders GFM tables natively. If your converter ignores your table, it's not using a GitHub-flavored Markdown parser.

The GitHub theme, and why it matters

You've already read thousands of Markdown pages on GitHub, so your eye expects that look: sans-serif body text, generous line height, muted inline-code chips, and a dark gray code block. Exporting to a PDF that matches that visual language means your document feels familiar and trustworthy — the reader isn't fighting the typography. The in-browser theme switcher lets you choose GitHub styling, a plain light sheet, or a dark sheet for presentations.

Real export scenarios

Exporting a resume

I keep my resume in Markdown — one source of truth, easy to edit with plain text. To send it as PDF, I paste it into the renderer, pick the GitHub theme, and check the live preview for three things: no page break splitting a job in half, margins that don't cram the text to the edge, and that the contact header sits cleanly at the top. Then I download. Editing the Markdown source and re-exporting takes seconds, which beats wrestling with Google Docs templates.

Exporting technical documentation

For internal runbooks or onboarding docs, Markdown is already the source. Rendering to PDF gives a portable version you can attach to a ticket or hand to someone without repo access. Because the render is local, even sensitive internal docs never leave your machine.

Mixing in images

If your Markdown references diagrams or screenshots, those images are embedded as you render. And if you want to append a set of exported figures — say, turn a folder of chart images into the back pages of the doc — the images-to-PDF tool combines them into a companion PDF you can merge in your reader.

Frequently asked questions

Does the PDF keep code syntax highlighting?

Yes, when the renderer uses highlight.js on fenced code blocks. The colors are baked into the printed page, so the PDF shows the same highlighting you see in the live preview — not plain black text.

Can I use GitHub-flavored tables?

Yes. A GFM parser renders pipe tables with real borders and alignment, the same way GitHub does. If your tables come out as raw text, the converter isn't parsing GFM.

Is my Markdown uploaded to a server?

In a browser-based tool, no — it's parsed and rendered on your own machine. The document text and any images you reference never leave the browser, which matters for resumes and internal docs.

Why does Pandoc need LaTeX?

Pandoc turns Markdown into a PDF by generating LaTeX and compiling it, so it needs a TeX distribution installed. It's powerful but a heavy setup; the browser route avoids that entirely.

Can I export a resume and tweak the margins?

Yes. A good browser renderer lets you set page margins and preview the first result before download, so you can avoid cramped edges or awkward page breaks.

Related reading