> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BankkRoll/repo2pdf/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Steps>
  <Step title="Run repo2pdf">
    Open your terminal and run:

    ```bash theme={null}
    npx repo2pdf
    ```

    This starts the interactive CLI with a welcome banner.
  </Step>

  <Step title="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
  </Step>

  <Step title="Provide repository URL">
    If you selected a remote repository, enter the GitHub URL:

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

    <Tip>
      The URL must be in the format: `https://github.com/username/repository`
    </Tip>

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

    ```
    ? Please provide the full path to the local repository: /Users/username/projects/my-repo
    ```
  </Step>

  <Step title="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
    ```

    <CardGroup cols={2}>
      <Card title="Add line numbers" icon="list-ol">
        Adds line numbers to the left of each code line
      </Card>

      <Card title="Add highlighting" icon="palette">
        Applies syntax highlighting using highlight.js
      </Card>

      <Card title="Add page numbers" icon="hashtag">
        Includes "Page X of Y" at the bottom of each page
      </Card>

      <Card title="Remove comments" icon="comment-slash">
        Strips code comments from the output
      </Card>

      <Card title="Remove empty lines" icon="compress">
        Removes blank lines to create more compact output
      </Card>

      <Card title="One PDF per file" icon="files">
        Creates separate PDFs for each file instead of one combined PDF
      </Card>
    </CardGroup>
  </Step>

  <Step title="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)
    ```
  </Step>

  <Step title="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
    ```

    <Note>
      Keeping the repository allows you to regenerate the PDF with different settings without re-cloning
    </Note>
  </Step>

  <Step title="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.
    ```
  </Step>
</Steps>

## Example: Converting repo2pdf itself

Here's a complete example converting the repo2pdf repository:

<CodeGroup>
  ```bash Terminal theme={null}
  $ 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.
  ```

  ```bash Local directory theme={null}
  $ npx repo2pdf

  ? Do you want to use a local repository? Yes
  ? Please provide the full path to the local repository: /Users/dev/projects/my-app
  ? Select the features you want to include: Add line numbers, Add highlighting
  ? Please provide an output file name: my-app.pdf

  Processing your request...

  ✔ Processing files... (32 processed)
  ✔ PDF created with 32 files processed.
  ```
</CodeGroup>

## 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:

```json repo2pdf.ignore theme={null}
{
  "ignoredFiles": ["tsconfig.json", "dist", "node_modules"],
  "ignoredExtensions": [".raw", ".log"]
}
```

<Note>
  For local repositories, place the `repo2pdf.ignore` file in the repository root. For remote repositories, the ignore file must be committed to the repository.
</Note>

## Tips for best results

<CardGroup cols={2}>
  <Card title="Use syntax highlighting" icon="paintbrush">
    Always enable syntax highlighting for code repositories - it dramatically improves readability
  </Card>

  <Card title="Add line numbers" icon="list-ol">
    Line numbers make it easier to reference specific code sections in discussions
  </Card>

  <Card title="Remove comments for summaries" icon="minimize">
    Use "Remove comments" when creating condensed overviews of large codebases
  </Card>

  <Card title="One PDF per file for large repos" icon="folder-tree">
    For repositories with 100+ files, consider using one PDF per file for easier navigation
  </Card>
</CardGroup>

## Common workflows

<AccordionGroup>
  <Accordion title="Code review preparation">
    Generate a PDF with line numbers and syntax highlighting:

    ```bash theme={null}
    npx repo2pdf
    # Select: Add line numbers, Add highlighting, Add page numbers
    ```

    Share the PDF with reviewers who can annotate and reference specific line numbers.
  </Accordion>

  <Accordion title="Portfolio documentation">
    Create a clean PDF without comments for project showcase:

    ```bash theme={null}
    npx repo2pdf
    # Select: Add highlighting, Remove comments, Remove empty lines
    ```
  </Accordion>

  <Accordion title="Code archival">
    Archive a snapshot with all details:

    ```bash theme={null}
    npx repo2pdf
    # Select: Add line numbers, Add highlighting, Add page numbers
    # Name: project-name-v1.2.0.pdf
    ```
  </Accordion>

  <Accordion title="AI training data preparation">
    Generate multiple PDFs for document processing:

    ```bash theme={null}
    npx repo2pdf
    # Select: One PDF per file, Add highlighting
    ```
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/usage/configuration">
    Learn about advanced customization options
  </Card>

  <Card title="CLI reference" icon="terminal" href="/advanced/api-reference">
    Explore all available features and options
  </Card>
</CardGroup>