How to convert a GitHub README to PDF (without it looking broken)

You need your README as a PDF — for a grant application, an offline handout, a client who lives in email attachments. You paste it into the first converter you find, and the output has dead links, gray-on-gray code, and a feature table split across two pages. Here’s how to get a version you’d actually send.

Start with a real Markdown renderer

A README isn’t plain Markdown. It’s GitHub Flavored Markdown: tables, task lists, footnotes, autolinks, fenced code. A converter that only handles CommonMark will quietly drop half of that — your - [x] checkboxes become literal text, your tables become walls of pipes.

So the first requirement is full GFM support. The second is syntax highlighting, because a README without colored code blocks reads like a wall of gray. Look for a tool that runs highlight.js or similar over your fences.

Keep the links live

The most common complaint about README PDFs is dead links. This happens for one reason: the tool flattened your page into an image. Images don’t have links.

The fix is to export a vector PDF through the browser’s print engine instead of a screenshot library like html2canvas. Vector PDFs keep your [text](url) anchors as real, clickable links — install instructions, badge targets, “see the docs” links all keep working in the file.

Quick test: export, open the PDF, and click a link. If nothing happens, the tool rasterized your page and you should use a different one.

Don’t let tables and code get cut

Feature comparison tables and longer code samples are exactly the elements that get sliced across page boundaries by default. The tool needs print CSS that says “keep these together”:

pre, table, img { break-inside: avoid; }
thead { display: table-header-group; } /* repeat header on each page */

Without break-inside: avoid, a 20-row table that crosses a page gets cut mid-row. Without display: table-header-group, page 2 of that table has no header, so the columns are anonymous. Both are one line of CSS, and most converters skip both.

The actual steps

1. Copy your README. Either paste the raw Markdown or drag README.md straight into the editor.
2. Pick a GitHub-style theme. You want the PDF to look like the README people already know.
3. Set page size and margins. A4 or Letter, and a normal margin (~18mm) reads well in print.
4. Check the preview. Confirm code is highlighted, tables are intact, and badges/images load.
5. Export PDF. Save it and do the two-second link-and-select test.

Keep it private

A README is usually public, but the conversion doesn’t have to involve a server. Tools that upload your file add latency, a privacy question, and a dependency on someone else’s rate limit. A client-side converter does the whole job in your browser — no upload, no account, no wait.

That’s how our Markdown-to-PDF tool works: full GFM, syntax highlighting, GitHub theme, vector output with live links, and break-inside rules so your tables and code stay whole. Drop your README in and export — free, and nothing leaves your browser. There’s a dedicated README to PDF page if you want to jump straight in.