Skip to main content

​
Output Modes

repo2pdf supports two distinct output modes:
  1. Single PDF - Combines all files into one PDF document
  2. One PDF per File - Creates a separate PDF for each source file
The output mode is controlled by the “One PDF per file” feature checkbox during configuration.

​
Single PDF Mode

By default (when “One PDF per file” is not selected), all repository files are combined into a single PDF document.

​
How It Works

let doc: typeof PDFDocument | null = null;
if (!onePdfPerFile) {
  doc = new PDFDocument({
    bufferPages: true,
    autoFirstPage: false,
  });
  doc.pipe(fs.createWriteStream(outputFileName));
  doc.addPage();
}
The tool creates one PDFKit document instance and appends all files to it sequentially.

​
Configuration

When using single PDF mode: 
? Select the features you want to include:
  ◯ One PDF per file

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

​
Features Available

All features work in single PDF mode:
  • Add line numbers
  • Add highlighting
  • Add page numbers (only available in this mode)
  • Remove comments
  • Remove empty lines

​
Page Numbers

Page numbers are only supported in single PDF mode: 
if (!onePdfPerFile) {
  doc.text("", { continued: false }); // ensure text flow is closed
  const pages = doc.bufferedPageRange();
  for (let i = 0; i < pages.count; i++) {
    doc.switchToPage(i);
    if (addPageNumbers) {
      const oldBottomMargin = doc.page.margins.bottom;
      doc.page.margins.bottom = 0;
      doc.text(
        `Page: ${i + 1} of ${pages.count}`,
        0,
        doc.page.height - oldBottomMargin / 2,
        { align: "center" }
      );
      doc.page.margins.bottom = oldBottomMargin;
    }
  }
  doc.end();
}
Page numbers appear centered at the bottom in the format: 
Page: 1 of 45

​
File Separation

Files are separated by newlines within the single PDF: 
// fix new line number starting on previous line
if (!onePdfPerFile && fileCount > 1) doc.text("\n");

​
Output Example

✔ PDF created with 47 files processed.
Creates: output.pdf (or your custom filename)

​
Use Cases

Complete Documentation

Generate a single comprehensive document for reading or sharing

Code Review

Review an entire codebase in one searchable PDF

Archival

Archive a snapshot of your repository in one file

Printing

Print the entire codebase as a physical document

​
One PDF per File Mode

When “One PDF per file” is selected, each source file gets its own dedicated PDF.

​
How It Works

if (onePdfPerFile) {
  doc = new PDFDocument({
    bufferPages: true,
    autoFirstPage: false,
  });

  const pdfFileName = path
    .join(outputFolderName, fileName.replace(path.sep, "_"))
    .concat(".pdf");

  await fsPromises.mkdir(path.dirname(pdfFileName), {
    recursive: true,
  });
  doc.pipe(fs.createWriteStream(pdfFileName));
  doc.addPage();
}
A new PDFKit document is created for each file, and each PDF is saved separately.

​
Configuration

When using one PDF per file mode: 
? Select the features you want to include:
  ◉ One PDF per file

? Please provide an output folder name: (./output)
Default folder: ./output

​
File Naming Convention

PDFs are named using the source file’s relative path with path separators replaced by underscores: 
const pdfFileName = path
  .join(outputFolderName, fileName.replace(path.sep, "_"))
  .concat(".pdf");

src/index.ts          → ./output/src_index.ts.pdf
lib/utils/format.js   → ./output/lib_utils_format.js.pdf
README.md             → ./output/README.md.pdf

​
Directory Structure

The output folder is created automatically with all necessary parent directories: 
await fsPromises.mkdir(path.dirname(pdfFileName), {
  recursive: true,
});
Example output structure: 
./output/
├── src_index.ts.pdf
├── src_components_Button.tsx.pdf
├── src_utils_helpers.ts.pdf
├── tests_unit_helpers.test.ts.pdf
└── README.md.pdf

​
Features Available

Most features work in one PDF per file mode:
  • Add line numbers
  • Add highlighting
  • Remove comments
  • Remove empty lines
  • Page numbers are NOT supported (each PDF is typically 1-2 pages)
Page numbers are automatically disabled in one PDF per file mode since each PDF contains only one source file.

​
Document Finalization

Each PDF is finalized immediately after its file is processed: 
if (onePdfPerFile) {
  doc?.end();
}

​
Output Example

✔ PDFs created with 47 files processed.
Creates: 47 individual PDFs in the ./output folder

​
Use Cases

Selective Sharing

Share individual files without exposing the entire codebase

Modular Review

Review files independently without scrolling through one large document

Parallel Processing

Distribute files to multiple reviewers

Organized Archives

Maintain file structure clarity in the output

​
Comparison

​
Advantages

  • One file to manage
  • Supports page numbers
  • Easy to search across all code
  • Better for sequential reading
  • Smaller total file size

​
Disadvantages

  • Large file size for big repositories
  • Harder to navigate to specific files
  • Must regenerate entire PDF for updates

​
Best For

  • Complete documentation
  • Code reviews of entire projects
  • Archival purposes
  • Printing

​
Processing Messages

The output message changes based on the mode: 
spinner.succeed(
  chalk.greenBright(
    `${
      onePdfPerFile ? "PDFs" : "PDF"
    } created with ${fileCount} files processed.`,
  ),
);

✔ PDF created with 47 files processed.

​
File Count Tracking

The tool tracks the number of files processed regardless of output mode: 
if (stat.isFile()) {
  fileCount++;
  spinner.text = chalk.blueBright(
    `Processing files... (${fileCount} processed)`,
  );
  // ... process file
}
This provides real-time feedback during processing: 
⠹ Processing files... (23 processed)

​
Memory Considerations

​
Single PDF Mode

Uses buffered pages to allow page number insertion: 
doc = new PDFDocument({
  bufferPages: true,  // Required for page numbers
  autoFirstPage: false,
});
This keeps all pages in memory, which can be intensive for large repositories.

​
One PDF per File Mode

Each PDF is written and closed immediately: 
if (onePdfPerFile) {
  doc?.end();  // Finalize and flush to disk
}
This is more memory-efficient for large repositories since only one file is in memory at a time.
For very large repositories (1000+ files), one PDF per file mode is recommended to avoid memory issues.

​
Choosing the Right Mode

Use Single PDF when:
  • You need page numbers
  • You want one file to manage
  • The repository is small to medium-sized
  • You need to print or archive the code
  • You want easy cross-file searching
Use One PDF per File when:
  • The repository is very large
  • You need to share specific files
  • You want clearer file organization
  • Memory usage is a concern
  • You need parallel review workflows

​
Next Steps

Configuration

Explore all available features and options

Basic Usage

Back to basic usage guide

Local Repositories

Process local repositories