merge-book-cover

dparedesi's avatarfrom dparedesi

Merge a cover image into a PDF book while preserving aspect ratio and matching width. Use when the user wants to "merge cover", "combine pdf", "fix cover size", or "add cover image".

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 25, 2025
[Document Processing]

When & Why to Use This Skill

This Claude skill automates the process of merging cover images into PDF documents with professional precision. It solves the common problem of misaligned or distorted covers by automatically detecting the document's page width and scaling the image to match perfectly while preserving the original aspect ratio, ensuring a clean, margin-free finish.

Use Cases

  • eBook Publishing: Seamlessly adding high-quality cover art to self-published books or technical manuals.
  • Corporate Branding: Standardizing internal reports and whitepapers by prepending a branded cover page without manual editing.
  • Digital Archiving: Fixing distorted or incorrectly sized covers in existing PDF libraries to ensure a consistent visual experience.
  • Automated Documentation: Integrating dynamically generated cover images into automated documentation pipelines for software projects.
namemerge-book-cover
descriptionMerge a cover image into a PDF book while preserving aspect ratio and matching width. Use when the user wants to "merge cover", "combine pdf", "fix cover size", or "add cover image".

PDF Cover Merger

Merges a cover image (PNG/JPG) into an existing PDF book, ensuring the cover matches the book's page width exactly while preserving its aspect ratio.

Why? Solving the problem of misaligned or distorted cover pages when combining images with PDF documents programmatically.

Quick Start

  1. Ensure assets/cover.png exists.
  2. Ensure docs/Data-Science-with-R.pdf exists.
  3. Run the script: python3 .agent/skills/merge-book-cover/scripts/merge_cover.py

Prerequisites

  • Python 3
  • Packages: img2pdf, pikepdf, Pillow

Workflow Steps

1. Install Dependencies

Ensure the required Python packages are installed.

python3 -m pip install img2pdf pikepdf Pillow

2. Verify Files

Ensure the source files are in place:

  • Cover Image: assets/cover.png
  • Book PDF: docs/Data-Science-with-R.pdf

3. Run Merge Script

Execute the script to resize the cover and merge it.

python3 .agent/skills/merge-book-cover/scripts/merge_cover.py

[!TIP] The script automatically detects the width of the book's first page and scales the cover to match it perfectly, avoiding white margins or distortion.

4. Verify Output

Check the output file: docs/Data-Science-with-R_FINAL.pdf.

Troubleshooting

Problem Cause Solution
ModuleNotFoundError Missing Python packages Run python3 -m pip install ...
FileNotFoundError Missing cover or book PDF check paths assets/cover.png and docs/...

| Aspect Ratio issues | N/A | Script auto-calculates height based on width. |

Quality Rules

  • Zero Distortion: The cover image must perfectly maintain its original aspect ratio.
  • Exact Width Match: The cover page width must exactly match the book's first page width (usually 612 pts for Letter).
  • No Margins: There should be no white bars or margins around the cover.
  • Automation: The process must run without manual image editing.

Testing & Evaluation

Manual Validation

  1. Run the script: python3 .agent/skills/merge-book-cover/scripts/merge_cover.py
  2. Open docs/Data-Science-with-R_FINAL.pdf.
  3. Check 1: Is the cover (Page 1) flush with the edges? (No white border)
  4. Check 2: Does Page 2 (Title Page) have the exact same width as Page 1?
  5. Check 3: Is the cover image undistorted (circles are circular, text is proportional)?