How to turn a GitHub README into a PDF

A practical guide · about 4 min read

Sooner or later someone wants your project's documentation as a PDF — to attach to a grant application, hand to a client, drop into a release archive, or read offline. The docs already live in README.md, so the job is really just “render this Markdown nicely and save it as a PDF.” Here's how to do that without the tables and code blocks falling apart.

The quick way: paste and print in the browser

For a one-off, you don't need to install anything:

Open your README.md and copy everything.
Paste it into the converter (or drop the file in).
Pick A4 or Letter, then Download PDF and choose “Save as PDF”.

It renders the README the way GitHub does — GFM tables, fenced code with highlighting, task lists — and prints from real HTML, so the PDF text stays selectable. Nothing is uploaded, which is useful for private repos.

What to check before you export

Badges and shields

Those status badges at the top of a README are small images loaded from a service like shields.io. In a PDF they look fine but they're decorative — if you're exporting for an offline archive, know that a badge is a snapshot of that moment, not a live status. Many people delete the badge row before exporting a “document” version, since it reads cleaner on paper.

Relative links and images

READMEs often link to other files with relative paths like docs/setup.md or embed an image from ./assets/logo.png. Relative links won't resolve outside the repo, and a relative image path won't load unless the image is reachable. For a portable PDF, switch embedded images to full https:// URLs, or paste the image in directly.

Tables and code

These are the two things most likely to look wrong if the converter is weak. Make sure tables use GitHub-Flavored Markdown and that code stays in fenced blocks. If you want the details on getting both to render cleanly, there's a dedicated guide on tables and code.

If you'd rather script it

If you export READMEs often, or want it inside a CI pipeline, the command-line route is Pandoc:

pandoc README.md -o README.pdf
# the PDF step needs a LaTeX engine such as TinyTeX installed

There are also Node tools like md-to-pdf that render with a headless browser, which handles GFM and highlighting closer to how GitHub shows it:

npx md-to-pdf README.md
# produces README.pdf next to the source file

Pandoc is best when you want templated, repeatable output; a browser tool is faster when you just need this one PDF now.

A tip for long READMEs

If your README is long, the section breaks can land awkwardly across pages. You can control where a new page starts — see the guide on page breaks and page size to keep, say, the “Installation” heading from being orphaned at the bottom of a page.

In short

A README is just Markdown, so exporting it to PDF is a solved problem: paste it into a browser converter for a quick private export, or wire up Pandoc / md-to-pdf if you need it automated. Either way you get a real, selectable-text PDF rather than a screenshot.