Quick start

Convert your first GitHub repository to PDF in under a minute

Your first conversion

Let’s convert a GitHub repository to PDF using the fastest method. This guide will have you generating your first PDF in under a minute.

1. Run repo2pdf

   Open your terminal and run:

   npx repo2pdf
   

   This starts the interactive CLI with a welcome banner.

2. Choose repository source

   You’ll be asked whether to use a local repository:

   ? Do you want to use a local repository? (Use arrow keys)
   ❯ No
     Yes
   

   • Select No to clone from GitHub
   • Select Yes to convert a local directory
3. Provide repository URL

   If you selected a remote repository, enter the GitHub URL:

   ? Please provide a GitHub repository URL: https://github.com/username/repo
   

   The URL must be in the format: https://github.com/username/repository

   Or if using a local repository, provide the full path:

   ? Please provide the full path to the local repository: /Users/username/projects/my-repo
   
4. Select features

   Choose the features you want to include using the space bar:

   ? Select the features you want to include:
   ❯ ◉ Add line numbers
     ◉ Add highlighting
     ◉ Add page numbers
     ◯ Remove comments
     ◯ Remove empty lines
     ◯ One PDF per file
   

   Add line numbers

   Adds line numbers to the left of each code line

   Add highlighting

   Applies syntax highlighting using highlight.js

   Add page numbers

   Includes “Page X of Y” at the bottom of each page

   Remove comments

   Strips code comments from the output

   Remove empty lines

   Removes blank lines to create more compact output

   One PDF per file

   Creates separate PDFs for each file instead of one combined PDF

5. Name your output

   Specify the output file or folder name:

   For single PDF mode:

   ? Please provide an output file name: (output.pdf)
   

   For one PDF per file mode:

   ? Please provide an output folder name: (./output)
   
6. Keep or delete clone

   For remote repositories, decide whether to keep the cloned repository:

   ? Do you want to keep the cloned repository? (Use arrow keys)
   ❯ No
     Yes
   

   Keeping the repository allows you to regenerate the PDF with different settings without re-cloning

7. Wait for processing

   repo2pdf will now:

   1. Clone the repository (if remote)
   2. Process each file with your selected options
   3. Generate the PDF(s) with syntax highlighting
   4. Clean up the temporary repository (if requested)

   ✔ Repository cloned successfully
   ✔ Processing files... (47 processed)
   ✔ PDF created with 47 files processed.
   

Example: Converting repo2pdf itself

Here’s a complete example converting the repo2pdf repository:

Terminal

$ npx repo2pdf

? Do you want to use a local repository? No
? Please provide a GitHub repository URL: https://github.com/BankkRoll/repo2pdf
? Select the features you want to include: Add line numbers, Add highlighting, Add page numbers
? Please provide an output file name: repo2pdf-source.pdf
? Do you want to keep the cloned repository? No

Processing your request...

✔ Repository cloned successfully
✔ Processing files... (15 processed)
✔ PDF created with 15 files processed.
✔ Temporary repository has been deleted.

Understanding the output

Single PDF mode

When generating a single PDF, repo2pdf creates one document containing all files from the repository:

• Each file starts with its relative path as a heading
• Files are separated by page breaks (when needed)
• Syntax highlighting is applied based on file extension
• Line numbers and page numbers are added if requested

One PDF per file mode

When using “One PDF per file”, repo2pdf creates a directory structure:

output/
├── src_main.ts.pdf
├── src_utils_helper.ts.pdf
├── README.md.pdf
└── package.json.pdf

Each file gets its own PDF with the same formatting options applied.

Customizing ignored files

By default, repo2pdf ignores common files like node_modules, .git, and binary files. To customize this, create a repo2pdf.ignore file in your repository root:

repo2pdf.ignore

{
  "ignoredFiles": ["tsconfig.json", "dist", "node_modules"],
  "ignoredExtensions": [".raw", ".log"]
}

For local repositories, place the repo2pdf.ignore file in the repository root. For remote repositories, the ignore file must be committed to the repository.

Tips for best results

Use syntax highlighting

Always enable syntax highlighting for code repositories - it dramatically improves readability

Add line numbers

Line numbers make it easier to reference specific code sections in discussions

Remove comments for summaries

Use “Remove comments” when creating condensed overviews of large codebases

One PDF per file for large repos

For repositories with 100+ files, consider using one PDF per file for easier navigation

Common workflows

Code review preparation

Generate a PDF with line numbers and syntax highlighting:

npx repo2pdf
# Select: Add line numbers, Add highlighting, Add page numbers

Share the PDF with reviewers who can annotate and reference specific line numbers.

Portfolio documentation

Create a clean PDF without comments for project showcase:

npx repo2pdf
# Select: Add highlighting, Remove comments, Remove empty lines

Code archival

Archive a snapshot with all details:

npx repo2pdf
# Select: Add line numbers, Add highlighting, Add page numbers
# Name: project-name-v1.2.0.pdf

AI training data preparation

Generate multiple PDFs for document processing:

npx repo2pdf
# Select: One PDF per file, Add highlighting

Next steps

Configuration

Learn about advanced customization options

CLI reference

Explore all available features and options