Kindle PDF Skill

E-reader PDF Optimization

When to load this skill

Load when the user asks any of:

• "Why is my PDF unreadable on Kindle / Kobo / e-reader?"
• "How do I convert / optimize / reformat a PDF for [small e-reader]?"
• "PDF排版在Kindle上一塌糊涂" (Chinese: PDF layout on Kindle is a mess)
• Anything involving "PDF" + "Kindle" / "e-ink" / "6 inch" / "reflow" / "排版" / "重排"

Especially when the PDF is a technical book (ML, math, CS) with matrices, code blocks, tables, or formulas — these are the cases where naïve approaches fail catastrophically.

Root cause: why technical PDFs look terrible on small Kindles

A 6-inch Kindle screen is ~90×120mm. A typical technical PDF page is 7-8 inches wide (Letter or B5). The user has two "obvious" options, both bad:

1. Keep it as PDF, drop onto Kindle (1:1 / "Original" mode) — text becomes too small to read. Kindle's PDF view is fixed-layout; pinch-zoom/pan works but is miserable for a whole book.
2. Convert PDF → AZW3 / MOBI / EPUB (Calibre, Send-to-Kindle email, ebook-convert, etc.) — text becomes the right size and reflows, BUT every 2D structure is destroyed: tables, matrices, code blocks, equations, side-by-side figures all get serialized into a single linear text stream. The user's diagnostic symptom: rows like 3 / the first token ID / over / 5 / dog / 1 / 1.2753 where each cell of a 2D table lands on its own line.

The reflowable-format conversion disaster is the #1 complaint and the giveaway diagnostic. If the user shows a screenshot with single-column-vertical-data fragments, that almost always means they tried to convert the PDF to AZW3/MOBI/EPUB (or used Kindle's experimental PDF reflow mode, which has the same effect). Don't let them go further down that path.

The fix is NOT to find a better reflowable format. The fix is to keep the PDF as a PDF and re-cut its pages to fit the 6-inch screen — which is exactly what k2pdfopt does.

Diagnostic checklist (do this first)

Before recommending a tool, gather these facts via vision/terminal:

1. PDF page size — mdls -name kMDItemPageHeight -name kMDItemPageWidth -name kMDItemNumberOfPages "/path/to.pdf" (macOS) or pdfinfo (poppler). Compare to the device screen.
2. PDF content type — text-only novel? Or technical with tables/code/math? This decides which tool to use.
3. Device screen size — Kindle 6" (Paperwhite/basic), Kindle Oasis 7", Kindle Scribe 10.2", Kobo Libra 7", etc. Ask if unclear.
4. What does the failure look like? — request a photo if possible, run vision_analyze to confirm reflow-disaster vs. tiny-text vs. wide-margins.

Solutions, ranked by quality for technical PDFs

🅰 k2pdfopt — best for technical books on 6-7" e-readers

Re-slices each PDF page into multiple smaller pages sized to the device, preserving the 2D structure of tables/code/equations while still being readable at the target screen size. The right answer for technical PDFs on 6" Kindle.

Recommend k2pdfopt when: technical content + 6-7" device. This is the durable best-practice recommendation; don't reach for Calibre first for technical books.

Install (macOS):

• brew install k2pdfopt — NOT IN HOMEBREW as of 2024-2026. Don't waste a turn trying.
• Official binary: https://www.willus.com/k2pdfopt/download/ — requires a 3-digit captcha + browser session. The captcha is fragile inside automated browser tools (Browserbase/stealth combos black out the page; vision can't reliably read the noisy 3-digit image). Best path: ask the user to download it themselves and pass you the binary path. Don't burn 10 tool calls fighting the captcha.
• Source build: GitHub mirror at remram44/k2pdfopt (official tarball mirror) or mo3rfan/k2pdfopt (has cmake fixes + Dockerfile). Requires cmake + several deps. Only attempt if the user explicitly allows git clone (some users have security policies that block it — see references/security-policy-pitfalls.md).

Post-download setup on macOS (manual binary):

# Strip Gatekeeper quarantine + provenance attrs, make executable, install globally
xattr -d com.apple.quarantine ~/Downloads/k2pdfopt 2>/dev/null
xattr -d com.apple.provenance ~/Downloads/k2pdfopt 2>/dev/null
chmod +x ~/Downloads/k2pdfopt
sudo cp ~/Downloads/k2pdfopt /usr/local/bin/k2pdfopt
file /usr/local/bin/k2pdfopt   # verify: Mach-O 64-bit executable arm64

Without removing com.apple.quarantine, the binary will be killed by Gatekeeper on first run with a vague "cannot be opened" dialog.

Run (the actual correct commands for technical PDFs on 6" Kindle):

# ⭐ RECOMMENDED for 6" Kindle reading 7-9" technical PDFs: fitwidth mode
# Slices each source page into 2-3 device-sized sub-pages, text gets bigger,
# code/matrices/equations stay intact horizontally.
k2pdfopt "input.pdf" -ui- -x -mode fitwidth -h 1024 -w 758 -dpi 212 \
  -as - -mc- -ws 0.01 -o "output_PW2.pdf"

# Same but for Paperwhite 3+ / Voyage / Oasis (higher-res screens)
k2pdfopt "input.pdf" -ui- -x -mode fitwidth -h 1448 -w 1072 -dpi 300 \
  -as - -mc- -ws 0.01 -o "output_PW3.pdf"

# 🎯 IF USER PREFERS HOLDING KINDLE PORTRAIT (most common): add -ls-
# Without -ls-, fitwidth rotates content sideways → user must hold Kindle landscape.
# With -ls-, content stays upright → user holds Kindle normally, reads ~390 pages
# (one source page = one device page; text smaller but standard orientation).
k2pdfopt "input.pdf" -ui- -x -mode fitwidth -h 1024 -w 758 -dpi 212 \
  -ls- -as - -mc- -ws 0.01 -o "output_PW2_portrait.pdf"

# 🎯 IF FONT IS TOO SMALL in portrait mode: bump font scale with -fs
# Tradeoff: larger font = more page breaks, but easier on the eyes.
k2pdfopt "input.pdf" -ui- -x -mode fitwidth -h 1024 -w 758 -dpi 212 \
  -ls- -fs 1.2 -as - -mc- -ws 0.01 -o "output_PW2_bigfont.pdf"

# For PROSE-heavy novels (no tables/code), full reflow looks best
k2pdfopt "input.pdf" -ui- -x -dev kp3 -mode fp -o "output_novel.pdf"

Landscape vs portrait output — explain this tradeoff to the user upfront so you don't have to redo the conversion:

Default recommendation depends on content type and device size:

• 6" device (PW1-PW4) + technical book with code/tables/equations → landscape (NO -ls-) is the default. Portrait + -fs cannot deliver enough text size for ML/math books at this screen size — physics, not preference. See references/physical-zoom-limits.md. User holds Kindle sideways but reads comfortably.
• 6" device + prose-heavy book → portrait (-ls-) is fine; reflow tools (Calibre AZW3) may actually be better here.
• 6.8"+ device (PW5, Signature, Oasis, Scribe) → portrait (-ls-) usually works even for technical content. Try it first.

If they specifically refuse landscape posture on 6" device for technical content, be honest: tell them the upper bound of comfort is what -fs 1.15 produces in portrait mode, and the durable fix is a bigger device. Don't promise a "one more flag will fix it" outcome — there isn't one.

Critical flags — read carefully, this is where session-after-session gets burned:

• -mode fitwidth — THIS is the right mode for technical PDFs on small screens. It splits each source page horizontally into multiple device-width sub-pages while keeping code/equation/table rows together. Each source page becomes 2-3 Kindle pages; final page count roughly doubles.
• -mode copy — MISLEADINGLY NAMED. Does NOT split pages. It only crops white margins and renders at original size. If the source PDF is 7×9 inches and device is 6 inches, copy mode output is still too big to read. The common mistake is assuming "copy" implies device-sized copy — it doesn't. Use fitwidth instead.
• -mode fp / -mode def — full reflow. Destroys 2D structure (same disaster as Kindle native reflow). Only OK for prose.
• -mode 2col — assumes 2-column academic paper layout.
• -h <px> -w <px> -dpi <ppi> — explicit physical device params. Prefer these over -dev presets when you know the exact device, because -dev presets bake in assumptions (e.g. kp3 assumes 1072×1448 @ 300ppi; using it for an older PW1/PW2 — 758×1024 @ 212ppi — produces sub-pages that are still too large).
• -dev <code> — device preset shortcut: kp2 (Paperwhite 2), kp3 (Paperwhite 3), kpw5 (Paperwhite 5/Signature), koa (Oasis), kv (Voyage), k3 (basic Kindle), dx (DX), kbg (Kobo Glo). Use only when device is clearly modern and you don't want to look up its exact pixels.
• -ui- — no interactive prompt (run unattended).
• -x — exit when done (don't open viewer).
• -as - — disable auto-skew correction (native PDFs aren't skewed; only enable for scans).
• -mc- — no markup/crop guides in output.
• -ws 0.01 — tight word-spacing threshold; helps the page-segmenter identify code blocks and matrices as atomic units.
• -n — keep native PDF text (selectable + searchable on Kindle). Without -n the output is bitmap (smaller file, no text selection).
• -rt 0 — intended to force no rotation. In -mode fitwidth with a large source page, this flag is effectively ignored — k2pdfopt still rotates content to fit the narrow device. Don't bother re-running with -rt 0 if your first output looks "rotated" in a viewer; see the rotation pitfall below. Use -ls- instead — that's the actual correct flag for "keep content upright on a portrait-held device."
• -ls- — THE correct flag for portrait-orientation output. Forces k2pdfopt to NOT rotate content into landscape. Without it, fitwidth rotates content sideways to maximize text width; with it, the content stays upright and each source page becomes ~1 device page (text is smaller, but Kindle is held normally). This is the parameter to reach for when the user complains about "having to hold Kindle sideways."
• -fs <factor> — font scaling. -fs 1.2 = "20% bigger" nominally. READ THE NEXT PITFALL before promising the user this will fix small text — on a 6" Kindle reading a 7-8" wide technical PDF, -fs only buys you ~10-15% perceived gain before it hits a hard wall, because the page width is already fully consumed by fitting one full source row into 758px. Tradeoff: more page breaks. See references/physical-zoom-limits.md for the math and the symptom: "I added -fs 1.25 but the text didn't actually get bigger."

A 300-400 page book takes 5-15 minutes on Apple Silicon; expect output to be 700-900 pages and 40-80 MB after fitwidth doubles the page count.

Device → physical params cheat sheet (for -h/-w/-dpi):

When in doubt about device age, ask the user for a photo and identify by bezel/logo (Paperwhite 2 has no logo on front, plastic flush bezel, no physical buttons, uneven front-light bleed). Old-device + new-preset = pages still too large.

🅱 Calibre — second choice, OK for plain text, mediocre for technical

brew install --cask calibre then ebook-convert input.pdf output.azw3 --output-profile kindle_pw3 --pdf-engine pdftohtml.

Limits: Calibre's PDF→EPUB/AZW3 path treats PDF as a flat text stream; it will mangle most tables, matrices, and code blocks the same way Kindle's native reflow does. Use it for novels and prose-heavy books only.

🅲 Kindle device-side settings — zero-install fallback

When the user can't or won't install anything:

• Settings → turn OFF "Reflow PDF" / "Enhanced View" (exact label varies by firmware). This forces original-layout display.
• Rotate device to landscape (orientation lock off).
• Use the crop tool to remove white margins (gives ~15% more usable area).
• For 6" devices reading technical PDFs: honestly tell the user this will never feel like reading on a laptop. A 10" Boox / Kindle Scribe / iPad is the physical fix.

Decision tree (give this to the user)

Is the PDF a novel / mostly prose?
├─ Yes → Calibre PDF→AZW3, or just use Kindle's reflow mode.
└─ No (technical, has tables/code/math):
   ├─ Device is 6-7" e-reader? → k2pdfopt with -dev <device> -mode copy
   ├─ Device is 10"+ (Kindle Scribe, Boox Note, iPad)? → Read PDF natively, no conversion needed.
   └─ User refuses to install tools? → Kindle landscape + original mode + crop.

Pitfalls

• THE BIG ONE: -fs N does not give you N× bigger text on a 6" Kindle reading a 7-8" technical PDF. A 758-pixel-wide 6" screen showing a 7.4" wide source page is already fitting 90 source-page characters into 758 pixels — every character is already at minimum-readable size. -fs 1.25 cannot magically widen the device; in -mode fitwidth -ls- (portrait, one source page → one device page) it produces only a marginal increase (10-15% perceived), not 25%. If a user says "I added -fs 1.25 but the text didn't actually get bigger" — believe them, this is the physics, not user error. The only ways to actually get +20-30% text on a 6" device reading a wide technical PDF are: (a) drop -ls- so each source page splits into 2-3 landscape sub-pages (user holds Kindle sideways, text is much bigger), (b) accept horizontal slicing that breaks code-line / table-row integrity, or (c) move to a 6.8"+ device. There is no fourth option — -fs alone won't get you there. Full math + measurements in references/physical-zoom-limits.md.

• For technical books on 6" devices, default to recommending landscape output (NO -ls-). The previous default in this skill was portrait + -fs 1.2 to "keep normal posture." In practice users come back and say "still too small." Landscape posture trades reading ergonomics for ~35% bigger text and is the durable answer for ML/math books on PW1-PW4 (6" screens). Mention the tradeoff explicitly so they choose with eyes open — but don't bury landscape as "alternative." Make it the headline option for technical content on 6" devices.

• -mode copy does NOT split pages — it only crops white margins. Despite the name suggesting "copy to device size," it renders at original page size. If source is 7×9" and device is 6", the output is still too big. Use -mode fitwidth for actual device-sized splitting. This is the single most common k2pdfopt mistake.

• -dev presets assume a modern device. -dev kp3 bakes in 1072×1448 @ 300ppi; on an older PW1/PW2 (758×1024 @ 212ppi) the resulting sub-pages are still oversized. Prefer explicit -h/-w/-dpi once you know the actual device generation.

• macOS quarantine kills manually-downloaded binaries silently. First run of ~/Downloads/k2pdfopt fails with a Gatekeeper dialog. Always xattr -d com.apple.quarantine + chmod +x before running.

• Don't recommend Calibre first for ML/math/CS books. Users come back disappointed. k2pdfopt is the right answer.

• Don't burn turns on the willus.com captcha if you're operating through automated browser tools — it's fragile. Ask the user to download manually.

• PDF page size ≠ device size. Always check both with mdls/pdfinfo before recommending a conversion approach.

• Brew has no k2pdfopt formula (as of last check). Don't try brew install k2pdfopt — it 404s.

• iCloud Drive paths: user's books may live at ~/Library/Mobile Documents/com~apple~CloudDocs/.... Quote the path; spaces and ~ expand correctly only when quoted.

• The reflow-disaster screenshot is the diagnostic — but ask about origin before assuming cause. If the user sends a Kindle photo showing single-column vertical data fragments, that almost always means they ran the PDF through a PDF→AZW3/MOBI/EPUB converter (Calibre, Send-to-Kindle email, ebook-convert) — NOT that Kindle's native PDF viewer mangled it. Kindle's native PDF mode is fixed-layout and renders the original PDF as-is (text just looks tiny on 6"); it does not auto-reflow into single columns. Before launching into k2pdfopt, confirm: "Is this the original PDF on Kindle, or did you convert it to AZW3/MOBI first?" The fix is the same (k2pdfopt on the original PDF), but the explanation you give the user must match reality — otherwise they'll think the problem is their Kindle and consider buying a new one. Full write-up in references/diagnostic-attribution.md.

• Transferring to old Kindle (Paperwhite 1/2): Send-to-Kindle email/cloud features are unreliable on these vintages. The durable path is USB — plug into Mac, the Kindle mounts as a disk named Kindle, drag the PDF into documents/, eject. Tell the user to set the PDF to "Actual Size" / "Original" view on-device (not Reflow) since k2pdfopt already did the work.

• DO NOT tell the user to email the k2pdfopt-optimized PDF via Send-to-Kindle. Amazon's Send-to-Kindle service auto-converts PDFs (to AZW/KFX on older firmware, or re-processes them), which will destroy the careful page slicing k2pdfopt did. The user will get the matrix-explosion / formula-fragmentation disaster all over again. USB transfer only for k2pdfopt outputs.

• Don't recommend converting to .mobi / .azw3 / .epub for technical PDFs. Users sometimes ask "do I need to convert PDF to mobi for Kindle?" The answer is NO — Kindle reads PDF natively. Mobi/AZW3/EPUB are reflowable formats; converting a technical book to them destroys code indentation, matrix alignment, and equation layout. The right answer for technical PDFs is "keep it as PDF, but use k2pdfopt to make it Kindle-sized."

• -rt 0 (force no rotation) does NOT keep the source page upright when the source page is bigger than the device in both dimensions. In -mode fitwidth, k2pdfopt always rotates internally to maximize width usage on the narrow device — the output PDF will still have content rotated relative to the source. Don't waste a re-run trying to get a "portrait" variant with -rt 0; the output is already correct and the device renders it correctly. The output page dimensions will be narrow+tall (e.g. ~257×348 pt for a 6" Kindle), matching the screen aspect ratio.

• DO NOT use vision_analyze to verify rotation of k2pdfopt output. Vision models systematically misjudge narrow+tall reflowed pages as "rotated 90°" because they pattern-match tall-rectangle = portrait-oriented-content. They will confidently produce wrong evaluations even when the output is correct. Correct verification paths:

  1. mdls -name kMDItemPageHeight -name kMDItemPageWidth <pdf> — narrow+tall (height > width, ~3:4 ratio matching the device) means correctly oriented for the device.
  2. pdftoppm -r 100 -f N -l N <pdf> /tmp/preview -png then ask vision a specific question: "scanning left-to-right across a row, do you see complete English sentences or single stacked letters?" If complete sentences → correct orientation. The generic "is this rotated?" question is unreliable.
  3. Trust the device. k2pdfopt outputs are reliably oriented; if metadata says narrow+tall, ship it.

• k2pdfopt errors out "File or folder - could not be opened" partway through a long book. Symptom: partial output PDF, "0 pages saved" for some source pages, exit code 0 but error message printed. Root cause: source PDF contains objects (font subsets, image dictionaries, etc.) MuPDF can't render cleanly. Fix: pass the source through ghostscript first, then feed the cleaned PDF to k2pdfopt:

  gs -o clean.pdf -sDEVICE=pdfwrite -dPDFSETTINGS=/prepress \
     -dCompatibilityLevel=1.5 source.pdf
  k2pdfopt clean.pdf [...other flags...]
  

  qpdf --linearize alone is NOT always enough — gs's full re-render is. See references/physical-zoom-limits.md for the session where this happened on Raschka's Build a LLM From Scratch.

See also

• references/k2pdfopt-flags.md — full flag reference and device codes
• references/physical-zoom-limits.md — read this when user says "text is still too small after running k2pdfopt" on a 6" device. Includes math, real measurements from the Raschka LLM book, and the durable answer (landscape, not flag tuning).
• references/diagnostic-attribution.md — distinguishing real causes (PDF→AZW3 conversion damage) from misattributed ones (blaming Kindle's PDF viewer)
• nano-pdf skill — for editing PDF text content, not for reformatting
• ocr-and-documents skill — for extracting text out of PDFs (different goal)