mdtopdf.

Document field notes

Sending a README as a PDF: what breaks when the repository is gone

A pre-export checklist for turning a repository README into a PDF: relative images and links, badges, issue references and the provenance a detached file needs.

Published 2026-10-24 · Markdown to PDF editorial

A README is written for a repository, not for a file attachment. Relative links, relative images and issue numbers all depend on the repository around them. Export the page and those relationships disappear, even when the headings and code blocks look perfect.

Why a README changes when it leaves the repository

GitHub resolves relative links and image paths against the current file and branch, so docs/setup.md or docs/architecture.png works while the README sits in its repository. The same text opened by a standalone converter has no repository to resolve against: the browser tries the path on the converter's own domain instead. The content is unchanged, but the context that made it navigable is gone.

Markdown to PDF renders the document in the browser and its product notes list image and video links among supported content. That means the converter will attempt the paths you give it. It cannot know where a relative path was supposed to point.

A small README that exposes the problem

This fixture contains the parts of a typical project README that depend on a host: a remote badge, a relative architecture image, relative documentation links and an issue reference.

# Widget service

[![CI](https://img.shields.io/badge/ci-passing-brightgreen)](https://example.com/ci)

A small service that renders widgets.

![Architecture](docs/architecture.png)

## Install

See [the setup guide](docs/setup.md) and issue #42.

[Contributing](CONTRIBUTING.md) · [License](LICENSE)

```bash
npm install widget-service
```

What one export actually did

The fixture was opened in the live preview and downloaded as a one-page PDF on 24 October 2026. This is a single observation, not a survey of converters or viewers, but it shows the failure modes clearly.

  • The remote badge survived. The shields.io image loaded and was embedded in the PDF. Its absolute link remained the only clickable destination in the file.
  • The relative image broke. docs/architecture.png was requested from the converter's domain, failed to load, and the PDF showed a broken-image icon with the alt text "Architecture".
  • The relative links became dead text. "the setup guide", "Contributing" and "License" were underlined like links, but the exported PDF contained no link annotations for them. They looked actionable and were not.
  • The issue number stayed plain text. "issue #42" did not become a link; only a full URL would give the reader a destination.
  • The code block survived intact. The install command kept its monospace formatting.

Prepare a detached copy, not the repository file

  1. Copy the README before editing. A detached PDF does not need to change the file your contributors read. Work on a copy so the repository version keeps its relative paths.
  2. Resolve images deliberately. For each image, decide whether the reader needs it. Decorative badges can go. A diagram should be replaced with an absolute URL that the recipient can reach, ideally pinned to a commit rather than a branch that will change. Never publish a private asset just to make a PDF render.
  3. Rewrite every relative link. Replace docs/setup.md with the full repository URL, ideally the blob URL at a specific commit. Keep the link text short; the URL belongs in the destination, not the sentence.
  4. Expand issue and pull-request references. Replace #42 with the full issue URL, or add a short "References" section at the end with the URLs spelled out. A reader who receives only the PDF cannot resolve a bare number.
  5. Prune badges and status images. A badge is a snapshot of a moving state. If the status matters, write the status and the date in text as well; otherwise remove the badge rather than imply it is current.
  6. Add provenance at the top. State the repository, the commit or version, the export date and who prepared the file. This is the information the repository normally supplies through its URL and history.

What survives and what does not

ElementInside the repositoryIn a detached PDF
Relative linkResolved by GitHub against the branchUnderlined text with no destination in the tested export
Relative imageLoaded from the repositoryRequested from the converter's domain; broken here
Remote badgeLoaded from its serviceEmbedded as a snapshot if the fetch succeeds
Issue reference #42Links to the issue on GitHubPlain text unless written as a full URL
Fenced code blockHighlighted codePreserved as a code block

Check the file before sending it

  1. Click every link in the PDF. Underlined text is not proof of a working link. If a destination is missing, fix the source and export again.
  2. Look for broken-image icons and alt text. Any image that failed to load leaves a visible gap or a placeholder. Replace it or remove it.
  3. Read the first page as a stranger. Does it say what project this is, which version, and where the canonical repository lives? If not, add the provenance block.
  4. Check the page count and the last section. A README often ends with licence and contribution details; confirm they were not pushed onto an orphaned final page by a long code block.
  5. Treat a private README as private. Exporting is still handling the document. Check the tool's data-handling description yourself before pasting internal repository content; this guide does not certify confidentiality.

Diagnose a README that exported badly

Images show a broken icon
The source used a repository-relative path. Replace it with an absolute, reachable image URL, or remove the image. Confirm the URL works in a private window before relying on it.
Links are underlined but do nothing
The destination is still relative. Rewrite it as a full URL. In the test export, relative links produced no PDF link annotations at all.
The badge disappeared
The remote image was blocked, slow or unavailable. A PDF should not depend on a third-party service at export time; write the status in text or drop the badge.
Issue numbers are useless to the reader
Expand them to full URLs. Bare issue references only work in a host that knows the repository.
The document has no clear owner or version
Add a provenance line with repository URL, commit, date and preparer. The PDF has left behind the page that would normally show that information.

Delivery checklist

  • A detached copy was edited; the repository README was left alone.
  • Every image uses an absolute URL or was removed.
  • Every link has an absolute destination and was clicked in the PDF.
  • Issue and pull-request references are expanded or listed at the end.
  • Badges are removed or backed by dated text.
  • Repository, commit, date and preparer appear on the first page.
  • Code blocks, licence text and contribution notes survived the page flow.
  • Private content was checked against the tool's data-handling description before export.

Sources and scope

Checked 24 October 2026. The workflow is editorial guidance. The preview and PDF observations come from one desktop browser session and one one-page export on that date; no cross-converter or viewer audit is claimed.