moonlight-lupin/agent-skills / productivity/pdf2epub
pdf2epub
VerifiedUse when converting a PDF book to EPUB, e.g. 'pdf to epub', 'convert this PDF book for my e-reader', 'EPUB with cover and TOC', 'pdf to ebook for kobo/kindle'. Builds a text-layer PDF into an EPUB with cover image, one section per chapter, a parsed 目录/Contents TOC, inline illustrations, and footnote endnotes. Text-layer PDFs only — scanned PDFs route to document-toolkit OCR.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.6 KB |
| references/calibration.md | markdown | 11.6 KB |
| requirements.txt | manifest | 41 B |
| scripts/pdf2epub.py | script | 36.0 KB |
| tests/test_pdf2epub.py | script | 3.2 KB |
SKILL.md
View on GitHub---
name: pdf2epub
description: "Use when converting a PDF book to EPUB, e.g. 'pdf to epub', 'convert this PDF book for my e-reader', 'EPUB with cover and TOC', 'pdf to ebook for kobo/kindle'. Builds a text-layer PDF into an EPUB with cover image, one section per chapter, a parsed 目录/Contents TOC, inline illustrations, and footnote endnotes. Text-layer PDFs only — scanned PDFs route to document-toolkit OCR."
license: MIT
metadata:
version: 1.3.0
author: moonlight-lupin
platforms: [linux]
hermes:
tags: ['pdf', 'epub', 'ebook', 'conversion', 'documents']
related_skills: ['document-toolkit', 'opendataloader-pdf']
---
# pdf2epub
## Overview
Convert a text-layer PDF to EPUB with real structure: cover image, one chapter per section, and a working 目录 (nav + ncx). Fully deterministic — no LLM in the conversion path. Engine: `scripts/pdf2epub.py` (pymupdf + ebooklib + Pillow).
## When to Use
- A text-layer PDF book should become an EPUB with cover + sections + TOC
- A printed 目录/Contents page needs parsing into real EPUB nav
- Footnote-heavy books (devotional/theological) need notes as linked endnotes, not body-text pollution
Don't use for: image-only scans (refused — route to document-toolkit OCR first) or PDF→Markdown extraction (that is opendataloader-pdf).
## Run
```bash
python scripts/pdf2epub.py \
input.pdf [-o out.epub] [--title T] [--author A] [--lang zh] [-v]
```
Needs `pymupdf`, `ebooklib`, `Pillow` (see `requirements.txt`). Create a dedicated venv for them if your environment pins system packages.
Optional flags: `--no-footnotes` keeps footnote text in body flow; `--scan` forces conversion of a scanless PDF.
**Done when:** exit 0, the report prints `sections` ≥ 1 with the expected chapter titles (check `-v` output), and the EPUB opens with its TOC intact. Verify deeper by zip-inspecting (see Verification).
## TOC resolution order
1. **Embedded TOC** (`doc.get_toc()`) — used when present; most reliable.
2. **Printed 目录/Contents page** — first page in the first 15 pages matching `/^目录$/` or `/Contents$/`. Line parser strips dot leaders (`....... N`) and keeps `(title, printed_N)`. Resolution searches pages `printed-3 … printed+40` for the title's first 16 chars, learns a single offset (majority vote), then maps every entry. Works when printed page numbers differ from PDF indices.
3. **Heading fallback** — font-size outliers vs page median. Crude. Check `-v` output before accepting.
## Cover
Strategy, in order of reliability:
1. **Single page-1 image covering ≥ 85% of the page area** → extract that image at native resolution (real cover art as one asset).
2. **Anything else** (multiple large images, a background texture with typography painted over it, no image) → **render the full page at 200 DPI**.
Learned from the Beeke book: page 1 had a full-bleed wood-grain texture (1500×1000) + a framed photo + text layers. Largest-image extraction picked the bare texture (a fragment); the actual cover exists only as the rendered composite. Extracting a single image is safe ONLY when it is the sole image and covers the page.
## Refusals
- Image-only PDF (no text layer): exits with error. Route to document-toolkit OCR first. `--scan` forces anyway (each page becomes one image-less chapter of garbage — only useful for testing).
- Dutch Annotations 1657 library PDFs are all scans — expect refusal there until OCR'd.
## Language
`--lang zh` for the Beeke-style CJK outputs; default `en`. PDF metadata rarely carries a language.
**Done when:** opening the built EPUB's nav shows front matter titled for the book's language (Front Matter for en) and no empty pre-chapter section for books whose cover page has no body text.
## Common Pitfalls
- Superscript flags are unreliable for footnote refs; gate on size + position (see references/calibration.md).
- Caption text visible at an illustration crop's top edge is usually part of the publisher's raster asset, not page bleed — don't crop art away to remove it.
- Run the engine inside an environment that has pymupdf, ebooklib, and PIL installed; a bare system python without them fails on import.
- Never classify lines before sections resolve — endnote-section detection needs the section list (classification gains an endnote-pages set from resolved sections).
- A bare-digit FNREF matching no note block renders as plain sup text, never as a dangling link.
## Footnotes
Per-page line classification with learned body font size (2-char-mode of line sizes, never hard-coded):
- FOLIO: bare 1-4 digit (or roman i-vi) number, font < 0.85*body, bottom 8% → dropped.
- FNREF: whole line is a bare digit, font < 0.75*body, any y → clickable `noteref` anchor at that spot. This book style (QuarkXPress CJK) emits refs as standalone 6pt lines; superscript flags unreliable.
- FOOTNOTE: font < 0.92*body, y > 0.60, not a list marker → grouped into note blocks (start = leading digit + body; continuations attach; bare-digit strays dropped) and rendered at the END of the containing chapter with `[n]` back-links. Ids are chapter-scoped (`fnc0-N`) because note numbering restarts per chapter.
- Body font size can exceed footnote-block height — footnote blocks may climb to 2/3 page.
Known limit: refs embedded INSIDE body lines as 5pt spans (merged into the text) don't get anchors; their notes still appear in the chapter footnote list. On the Beeke book: 41 anchored / 58 notes.
`--no-footnotes` keeps footnote text in body flow as plain text.
## Inline illustrations
Every non-cover illustration is extracted as a page-surface CROP, not a raw xref: render the page at 140 DPI and cut the image bbox (`page.get_pixmap(matrix=…, clip=…)`, the marker approach without its AI layer). Crops survive composed/vector art and CMYK/mask oddities. Raw-xref extraction stays only for the cover.
- Geometry from `page.get_image_info()` — no AI layout model needed.
- Filters: area ≥ 3% of page (drops icons/logos), pixel-sha256 dedup (drops art shared across pages, pdf-craft's move), optimized crops < 2 KB dropped (near-blank).
- PIL optimizer: LANCZOS downscale to ≤ 1600 px, alpha compositing onto white, JPEG q85.
- Figures interleave per page, after that page's body text, as `<figure class="illus">`.
- Top-of-image caption text that looks clipped ("letters cut at the crop edge", different typeface) is usually INSIDE the publisher's raster asset — not bleed from the page. Check PDF text-line intersection first; if no overlap, the caption is part of the artwork and must ship with it. Do not cut art away trying to remove it.
- The cover page's ≥ 85% image is excluded (it ships as the cover).
## Verification Checklist
```bash
python3 - <<'EOF'
import zipfile, re, collections
z = zipfile.ZipFile("OUT.epub")
ok = True
for n in z.namelist():
if not n.endswith(".xhtml") or "/nav" in n or "cover" in n:
continue
c = z.read(n).decode()
ids = set(re.findall(r'id="([\w-]+)"', c))
dup = [k for k, v in collections.Counter(re.findall(r'id="([\w-]+)"', c)).items() if v > 1]
bad = []
for h in re.findall(r'href="#([^"]+)"', c):
if ".xhtml#" in h: # cross-file: secNNN.xhtml#anchor
f, aid = h.split(".xhtml#")
full = "EPUB/" + f + ".xhtml"
if full not in z.namelist() or aid not in ids | set(re.findall(r'id="([\w-]+)"', z.read(full).decode())):
bad.append(h)
elif h not in ids:
bad.append(h)
if bad or dup:
ok = False
print(n, "bad", bad, "dup", dup)
print("LINK CHECK:", "PASS" if ok else "FAIL")
EOF
```
- [ ] report: `sections ≥ 1`, `toc_source` matches the book (embedded vs printed)
- [ ] `-v` lists every expected chapter at a sane PDF page
- [ ] link check above: 0 missing targets, 0 duplicate ids
- [ ] cover renders complete (texture + titles + credits all present) — eyeball it once per new book
## Verified on
BEEKE-Covenant-Children (96 pp, CJK QuarkXPress-style): printed 目录 page 3 → 5 chapters resolved; cover = full-page 200-DPI render, visually verified complete; title from cover fonts; 58 notes dense per chapter (23/5/25/5); 41 noterefs all resolve, 0 broken targets, 0 duplicate ids; 94 folios dropped.
BEEKE-Parenting-zh (405 pp, CJK): global-endnotes book — 127 notes in one 注释 chapter (sec030), 50 cross-file noterefs secNNN.xhtml#fnc30-N + back-links; 32 nav sections 前言→注释 incl 第二十/二十一章 + 附录1; 4 inline crops; cover 200-DPI render. Cross-file hrefs must not double-#'d (see references/calibration.md).
Engine A/B: koreyba/Claude-Skill-pdf-to-epub was trialed on the same book and lost on TOC (3 chapters), nav, cover, title, and endnote cleanliness — not adopted. Alternatives live upstream, not in this skill's tree.Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |