For Developers

Written and tested by the MD Converter editorial team

How to Convert a GitHub README into a PDF

How to turn a GitHub README.md into a clean PDF—handling badges, code blocks, and relative links so the exported document doesn't fall apart.

What you'll learn

  • How to convert a GitHub README.md straight into a PDF
  • Why badge images and relative links tend to break in the export
  • How to keep code blocks and syntax highlighting intact
  • Tips for making the result print-friendly for internal reports or audits

A README looks fine on GitHub, but exporting it as a PDF often surfaces problems: badge images fail to load, relative links break, or code blocks get clipped. If you need to turn repository documentation into a PDF for an internal report or audit, here's a process that avoids the usual breakage.

Steps: turn README.md into a PDF

  1. Open the raw text of README.md from GitHub, or open the local file in an editor.
  2. Download or save the README as a .md file and load it into a PDF converter that supports GitHub Flavored Markdown.
  3. Check the preview for badge images, heading structure, and code block rendering.
  4. Generate a table of contents from headings if needed, then adjust margins and fonts through print CSS or converter settings.
  5. Click Save as PDF to export.

For the general Markdown-to-PDF workflow beyond READMEs, see How to Print Markdown or Save It as PDF.

Badge images not showing up

Badges like ![Build Status](https://img.shields.io/...) at the top of a README are loaded via requests to an external service. Depending on network conditions or access restrictions, these images might not load at export time, showing up as blank or broken icons. For badge-heavy READMEs, check the preview before distributing the PDF. If an image doesn't load, try again later, or prepare a separate copy with the badge line removed for formal submissions.

Relative links breaking

READMEs commonly link with repository-relative paths, like [Usage](./docs/usage.md). These only resolve within GitHub's repository structure, so exporting the Markdown on its own leaves them broken. If the PDF's purpose is just to convey document structure, broken links are often acceptable—but if you need working references, replace them with absolute GitHub URLs (https://github.com/user/repo/blob/main/docs/usage.md) before pasting.

Code blocks and syntax highlighting

READMEs often include install steps or API examples in ```bash or ```js code blocks. Long commands or wide code can get wrapped or clipped at the page width, so check the preview and consider landscape orientation or a smaller code font in print CSS.

Use the table of contents for readability

READMEs tend to have deep heading hierarchies (installation, usage, API, contributing...), so turning on the table of contents feature makes it much easier to jump to a section in the exported PDF. See Adding a table of contents to Markdown PDF for details.

Bundling multiple repos' READMEs

To combine READMEs from several internal projects into one document, add a # Project Name heading before each one before concatenating. The table of contents feature will then produce a document clearly sectioned by project.

FAQ

Badge images don't show up in my PDF

Badges are images loaded from an external service, so they may fail depending on network conditions. Check the preview first; if they still don't load, retry later or prepare a copy with the badge line removed for submission.

Links in my README PDF don't go anywhere

Repository-relative links can't resolve once the Markdown is exported standalone. Replace them with absolute GitHub URLs before converting to avoid broken links.

Code blocks run off the page

Long commands or wide code can wrap or get clipped. Try landscape orientation or a smaller code font in the print stylesheet.

What if I need to submit the README as a Word file?

Use Pandoc or another compatible converter to create a docx when the recipient plans to edit the document further.

Should repository navigation remain in the PDF?

Remove badges, contribution shortcuts, issue links, and status widgets that do not help the PDF reader. Keep installation, usage, configuration, license, and support information. A submission document should be edited for its recipient rather than acting as a screenshot of the repository page.

Before export, search for private clone URLs, internal hostnames, access tokens, and branch-specific links. Confirm that every retained image and link works without your signed-in GitHub session.

Summary

The two things most likely to break when exporting a GitHub README as a PDF are badge image loading and relative link resolution. Check the preview before exporting, and clean up badges or links as needed for a submission-ready PDF.

Convert your GitHub README to PDF

Related