Guide

How to Convert a GitHub README to PDF

June 27, 2026 · 5 min read

Your README is often the best documentation a project has, but it lives inside GitHub. Sometimes you need it as a standalone file you can email, print, or archive. This guide shows three reliable ways to convert a GitHub README to PDF, plus fixes for the badges, tables, and images that usually break along the way.

Why turn a README into a PDF?

A Markdown file is great for the web and terrible for handoffs. A PDF solves that:

Offline deliverables. Ship documentation to a reviewer who has no repo access and no internet.
Grant and portfolio submissions. Funders and hiring panels want a clean, page-numbered document, not a link that might 404 next year.
Archiving. Freeze the state of your docs at a release or milestone so it never drifts.
Client handoff. Hand a customer a polished spec instead of pointing them at github.com.

The trick is that GitHub renders your README with its own flavor of Markdown, its own badges, and its own image resolution. A naive conversion loses all of that. Below, each method keeps as much fidelity as possible.

Method 1: Paste the raw README into a browser converter (recommended)

The fastest and most private route needs no installs. You grab the raw Markdown and paste it into a converter that runs entirely in your browser.

First, get the raw source. On any repo's README, click the Raw button, or go straight to the raw URL pattern:

https://github.com/<user>/<repo>/raw/main/README.md

Older repos may use master instead of main. This gives you the exact Markdown text, not GitHub's rendered HTML. Select all, copy it.

Now open ConvertMDapp, paste into the editor, and watch the live two-way preview render it instantly. When it looks right, export a clean PDF. You can also download the .md if you want a tidied copy of the source.

Why this method wins for most people:

Nothing uploads. The conversion runs 100% in your browser, so your README never leaves your device. That matters for private repos and unreleased docs.
No signup, no watermark. You get a clean PDF, free, with nothing stamped across it.
You can fix things before exporting. Tables in the preview are editable, code stays syntax-highlighted, and you can flip between light and dark theme to match your deliverable.

If your README leans heavily on tables, the companion guide on converting Markdown tables to PDF covers alignment and wide-column fixes in detail.

Method 2: The VS Code Markdown PDF extension

If the README is already open in your editor, you may not want to leave it. Install the Markdown PDF extension (yzane.markdown-pdf) from the Extensions panel.

Then:

Open your README.md.
Open the command palette (Cmd/Ctrl+Shift+P).
Run Markdown PDF: Export (pdf).

The PDF lands next to your file. This is convenient for a repo you already have cloned, and it respects local relative image paths because it runs from your working copy. The tradeoff: it uses a generic Markdown renderer, so GitHub-specific styling and some GFM extensions may look different from github.com.

Method 3: The command line

For scripting or CI, stay in the terminal. Two approaches, depending on how close to GitHub's look you need to be.

Option A — grip for authentic GitHub styling. grip renders Markdown using GitHub's own rendering, then you print to PDF:

pip install grip
grip README.md --export README.html
# then print README.html to PDF from any browser, or:
wkhtmltopdf README.html README.pdf

Option B — gh + pandoc. Pull the rendered or raw Markdown and convert with pandoc:

gh api repos/<user>/<repo>/contents/README.md \
  --jq '.content' | base64 -d > README.md
pandoc README.md -o README.pdf

Pandoc needs a LaTeX engine for PDF output. It is powerful but strays furthest from GitHub's visual style, so expect to tune a template.

GitHub-specific gotchas (and how to fix them)

This is where conversions go wrong. GitHub does a lot of work behind the scenes that a plain converter cannot guess.

shields.io badges

Those colorful build/version badges are images, usually from shields.io. They are fetched from the internet at render time. If you convert offline, or the badge service is slow, they break or vanish. Options: keep an internet connection when you export, replace critical badges with plain text, or delete decorative ones for a print deliverable where they add noise.

Relative image paths

A README often references images like ![diagram](docs/diagram.png). That path only resolves inside the repo. Pull the Markdown out and it points nowhere. Fix it by swapping in absolute raw URLs:

![diagram](https://raw.githubusercontent.com/<user>/<repo>/main/docs/diagram.png)

Now the image resolves from anywhere, including a browser converter.

GitHub-Flavored Markdown features

GFM adds syntax that basic renderers ignore. Check these before you trust the output:

Feature	GFM syntax	Common failure
Task lists	`- [x] done`	Renders as literal brackets
Tables	`\| a \| b \|`	Columns collapse or misalign
Strikethrough	`~~text~~`	Tildes show literally
Fenced code	```lang	No syntax highlighting

A converter that understands GFM, like the live preview at ConvertMDapp, renders all four correctly, so you can confirm them at a glance before exporting.

Emoji

Shortcodes like :rocket: are a GitHub convenience, not standard Markdown. Many renderers print the literal :rocket: text. If emoji matter to your document, paste the actual Unicode character (🚀) into the source instead of the shortcode.

Putting it together

For a private, no-install, high-fidelity result, Method 1 is hard to beat: grab the raw file, paste it in, fix badges and image paths, export. Reach for VS Code when the repo is already cloned, and the command line when you are automating. For the broader picture on Markdown-to-PDF workflows, see the complete guide to converting Markdown to PDF.

FAQ

Why does my README look broken after converting? Almost always badges or relative image paths. Badges are internet-hosted images, and relative paths only work inside the repo. Swap image links to absolute raw.githubusercontent.com URLs and keep a connection while exporting.

Do I have to upload my README anywhere? No. A browser-based converter that runs entirely on your device never sends the file anywhere, which is the safest choice for private or unreleased documentation.

Can I convert a private repo's README? Yes. Copy the raw Markdown from the private repo (you are already authenticated on github.com), then paste it into an in-browser converter so the text stays local to your machine.