Skill: bunsdev/epub-to-pdf (version 1.1.0)

--- name: "epub" description: "Convert EPUB ↔ PDF bidirectionally. EPUB→PDF preserves layout for analysis; PDF→EPUB compresses and reflows for distribution and ereaders." --- # EPUB Skill ## When to use ### EPUB → PDF - Convert EPUB books, papers, or distributed documents to PDF for reading and analysis - Preserve layout and formatting before text extraction via pdftoppm - Archive EPUB content in a fixed-layout format - Prepare EPUBs for downstream processing (rendering, analysis, synthesis) ### PDF → EPUB - Convert papers and PDFs to reflowable EPUB format for ereader distribution - Compress PDFs into smaller, device-friendly EPUB archives - Auto-detect chapters and structure for better reading experience - Redistribute research materials in open formats ## Workflow ### EPUB → PDF (for analysis) 1. **Check for calibre** → install if missing (`brew install calibre`) 2. **Convert EPUB → PDF** using `ebook-convert` with formatting options 3. **Validate output** → confirm PDF rendered correctly 4. **Render pages** → use pdftoppm to extract visual content 5. **Analyze** → pass to PDF skill for text extraction and synthesis ### PDF → EPUB (for distribution) 1. **Check for calibre** → install if missing 2. **Convert PDF → EPUB** using `ebook-convert` with reflowable settings 3. **Auto-detect chapters** → ebook-convert scans for structure 4. **Validate compression** → confirm EPUB is smaller than PDF 5. **Archive** → save EPUB to `research/sources/` for distribution or ereader use ## Usage ### EPUB → PDF (basic) ```bash ebook-convert input.epub output.pdf ``` ### EPUB → PDF (with layout preservation options) ```bash ebook-convert input.epub output.pdf \ --pdf-standard-font "sans" \ --paper-size "a4" \ --margin-left 20 \ --margin-right 20 \ --margin-top 20 \ --margin-bottom 20 \ --pdf-mono-family "mono" ``` **Note:** Valid font families are: `serif`, `sans`, `mono` (not Helvetica, etc.) ### PDF → EPUB (basic) ```bash ebook-convert input.pdf output.epub ``` ### PDF → EPUB (with compression) ```bash ebook-convert input.pdf output.epub \ --output-profile "tablet" \ --paper-size "a4" ``` **Note:** `ebook-convert` auto-detects chapters from PDFs. Inspect the output EPUB to verify structure. ### In context (Sage workflow) #### EPUB → PDF ```bash # Convert EPUB to PDF for analysis ebook-convert "/path/to/input.epub" "/path/to/research/sources/output.pdf" # Verify and check size ls -lh "/path/to/research/sources/output.pdf" # Render pages for visual inspection pdftoppm -png "/path/to/research/sources/output.pdf" "/tmp/preview/page" ``` #### PDF → EPUB ```bash # Convert PDF to EPUB for distribution ebook-convert "/path/to/input.pdf" "/path/to/research/sources/output.epub" # Verify compression ls -lh "/path/to/input.pdf" "/path/to/research/sources/output.epub" # (EPUB will typically be 30-50% of PDF size) ``` ## Dependencies **System package:** ```bash # macOS (Homebrew) brew install calibre # Ubuntu/Debian sudo apt-get install -y calibre # Fedora/RHEL sudo dnf install calibre ``` `calibre` includes `ebook-convert` and supports many formats: - Input: EPUB, PDF, MOBI, AZW, AZW3, HTML, TXT, DOCX, ODT - Output: EPUB, PDF, MOBI, AZW, AZW3, DOCX, HTML, TXT ## Output conventions - **Location:** Save files to `research/sources/` with descriptive names - **Naming:** Use title or slug: `Author-Title.pdf`, `title-yyyy-mm-dd.epub` - **EPUB→PDF:** Check size (>100 KB typical for books) - **PDF→EPUB:** Typically 30-50% of PDF size due to reflowable format - **Cleanup:** Remove temporary files after verification ## Quality checks ### After EPUB → PDF: 1. File exists and readable 2. File size >100 KB (suspiciously small = text-only, may have lost images) 3. `file output.pdf` confirms it's a valid PDF 4. pdftoppm renders first page successfully ### After PDF → EPUB: 1. File exists and readable 2. File size is 30-50% of original PDF (good compression ratio) 3. Unzip the EPUB and inspect `content.opf` for auto-detected chapters 4. Open in ereader or calibre viewer to verify reflowable layout ## Troubleshooting ### EPUB → PDF crashes or produces empty output - Check if EPUB is corrupt: `unzip -t input.epub` - Try without formatting options: `ebook-convert input.epub output.pdf` - If EPUB has missing stylesheets (common), calibre will warn but continue - Last resort: extract text from EPUB (`unzip -p input.epub` | grep -r "html") and convert to markdown ### PDF → EPUB produces wrong chapter detection - Run with `--verbose` to see what calibre detected: `ebook-convert input.pdf output.epub --verbose` - For scanned PDFs (images), conversion may fail or produce text-only EPUB - Use pdftotext first to extract text, then create EPUB from markdown ### File size issues - EPUB→PDF: if output is <50 KB, likely text-only (no images captured) - PDF→EPUB: if output is >150% of input, likely includes images; use `--output-profile "tablet"` for better compression ## Notes - **Layout preservation (EPUB→PDF):** `ebook-convert` maintains structure, typography, images - **Reflowable format (PDF→EPUB):** EPUB reflows to device width; fixed-layout PDFs may lose structure - **Chapter detection (PDF→EPUB):** Automatic; works best on PDFs with clear page breaks or bookmarks - **Scanned PDFs:** May fail or produce text-only output (no OCR) - **Large files:** Some books convert to large files (100+ MB PDFs/EPUBs). Normal. ## When conversion fails - **EPUB is corrupt:** `unzip -t input.epub` (EPUBs are ZIP files) - **Verbose output:** `ebook-convert input.epub output.pdf --verbose` for error details - **Unsupported format:** Request original source in different format - **Manual fallback:** Extract text from EPUB or PDF, save as markdown, document the failure ## Related - [PDF Skill](/concepts/pdf) — for reading and rendering converted PDFs - [pdftotext](https://manpages.ubuntu.com/manpages/xenial/man1/pdftotext.1.html) — text extraction from PDF - Calibre Handbook: https://manual.calibre-ebook.com/ ## Tested Conversions ✅ **SHELLFISH.epub → SHELLFISH.pdf** (73 KB → 639 KB, layout preserved, 89 pages) ✅ **SHELLFISH.pdf → SHELLFISH-test.epub** (639 KB → 262 KB, chapters auto-detected, 24 parts) --- _EPUB ↔ PDF bidirectional conversion pipeline ready._ _Last tested: 2026-04-29 | Calibre v5.x_


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)