md2pdfGuides

README to PDF

How to convert a README.md to PDF

A README works well in a repository, but sometimes you need to send it to clients, teachers, or teammates as a stable document. This guide shows how to clean it up, verify its structure, and export it to PDF.

Practical guide · 5 min

Before converting

  • Use one main title and organize the rest with subheadings.
  • Check that absolute links still work outside the repository.
  • Label code blocks with a language to keep them readable.

01

From repository to document

  1. Review the hierarchy

    Keep one H1 heading for the project. Use H2 for installation, usage, and configuration, and H3 only when a section needs another level.

  2. Fix relative resources

    An image such as ./docs/screenshot.png depends on the repository. For a portable document, use a stable public URL or remove resources containing internal information.

  3. Check code and tables

    Label the code language and avoid overly wide tables. A short table fits A4 or Letter pages more reliably.

  4. Adjust and export

    Load the README, select the page size, and inspect the preview. For a long document, enable the table of contents before downloading the PDF.

README to PDF

Try a short README

Edit the description or add a requirement. The preview renders Markdown without running HTML or scripts.

Open in converter

You can edit the example here. Opening it in the converter loads the original version so you can export it.

Editable Markdown
Preview

Atlas CLI

A small tool that validates configuration files before deployment.

Installation

bash
npm installnpm run build

Usage

  1. Copy .env.example to .env.
  2. Run npm run validate.
  3. Fix warnings before publishing.
CommandPurpose
npm testRun the tests
npm run buildCreate the final build
Tip: never include secrets or credentials in a README.

02

Details that improve the PDF

  • Remove badges and counters that only make sense inside the repository.
  • Replace directions such as “click above” with instructions that work on a page.
  • If the README includes a full license, consider moving it to a new page with an explicit page break.

03

Frequently asked questions

Is the README sent to a server?

No. md2pdf reads and converts the content inside your browser.

Are code blocks preserved?

Yes. The PDF keeps the block, its language label, and wraps long lines.