DEV Community: Selenium39

Antes de publicar tu EPUB: vista previa en tinta electrónica, metadatos, portada y tamaño, sin instalar nada

Selenium39 — Fri, 02 Oct 2026 23:41:34 +0000

Si generas EPUBs con Pandoc, Sigil, Quarto, mdBook o tu propio script, seguro que te ha pasado: en el ordenador el libro se ve perfecto, pero en un Kindle o un Kobo las imÃ¡genes salen negras, el tÃtulo aparece como "Untitled" y el archivo pesa 90 MB.

Esta es una lista de comprobaciÃ³n para revisar un EPUB antes de enviarlo a un lector de tinta electrÃ³nica. Todo se hace con herramientas gratuitas de E-Ink que funcionan en el navegador, sin subir el archivo a ningÃºn servidor.

Para EPUBs sin DRM: libros propios, documentaciÃ³n, apuntes, obras de dominio pÃºblico.

1. Â¿CÃ³mo se ve en tinta electrÃ³nica?

Abre la vista previa EPUB para e-ink. Acepta EPUB, MOBI, AZW3, FB2, FBZ y CBZ.

Dispositivo: Kindle (11.Âª gen.) 1072Ã—1448, Kindle Paperwhite (11.Âª gen.) 1236Ã—1648, Paperwhite (12.Âª gen.) 1264Ã—1680, Kobo Clara BW, Kobo Libra 2 / Colour.
Modo de pantalla: blanco y negro, 4 niveles de gris o color.
TipografÃa: tamaÃ±o de letra, con serifa o sin serifa.
Texto vertical (CJK) para libros en japonÃ©s o chino.
Marco del dispositivo opcional.

QuÃ© revisar:

Problema	Por quÃ© pasa	SoluciÃ³n
Diagramas que se vuelven manchas	Grises oscuros que se funden con 4 niveles	MÃ¡s contraste, o lÃneas en vez de rellenos
Pies de foto ilegibles	`color: #aaa` en el CSS	Texto secundario como mucho en `#555`
Tablas que se salen	Anchos fijos en `px`	Usa `%` o `em`, o convierte la tabla en lista
Bloques de cÃ³digo cortados	`white-space: pre` sin ajuste	`pre { white-space: pre-wrap; }`

Ojo: es una simulaciÃ³n con filtros de escala de grises y contraste. Sirve para iterar rÃ¡pido, pero no sustituye a Kindle Previewer para la revisiÃ³n final si vas a publicar en KDP.

2. Metadatos: lo que se ve en la estanterÃa

El tÃtulo y el autor que muestra el lector salen del archivo OPF del EPUB, no del nombre del archivo. Si en Pandoc olvidaste el bloque title/author, el libro aparecerÃ¡ sin tÃtulo.

El editor de metadatos EPUB permite cambiar:

tÃtulo, autor, ISBN, idioma, editorial y descripciÃ³n

Los campos que dejes vacÃos conservan su valor (no se borran). Pon el idioma correcto (es): el lector lo usa para la separaciÃ³n silÃ¡bica y el diccionario.

Si despuÃ©s de cambiarlo el lector sigue mostrando el tÃtulo antiguo, borra el libro del dispositivo y vuelve a copiarlo; suele ser cachÃ©.

3. Portada

Cambiar portada EPUB: reemplazar, aÃ±adir o quitar la portada, con la actual y la nueva lado a lado.
Extraer portada EPUB: guarda la portada actual como imagen antes de cambiarla.

En tinta electrÃ³nica la portada se ve en grises. Comprueba que el tÃtulo contraste por luminosidad, no solo por color.

4. TamaÃ±o del archivo

Si tu libro tiene muchas imÃ¡genes a resoluciÃ³n de impresiÃ³n, el compresor EPUB te muestra el porcentaje que ocupan las imÃ¡genes y ofrece estos presets:

Sin pÃ©rdida: solo reempaqueta.
Equilibrado: imÃ¡genes de hasta 1920 px.
Lector electrÃ³nico (recomendado): hasta 1400 px, pensado para pantallas de 6â€“8".
Extremo: hasta 800 px.
TamaÃ±o objetivo: indicas los MB y reintenta hasta conseguirlo.

5. Recuento de palabras

El contador de palabras EPUB da el total de palabras y caracteres, el desglose por capÃtulo y el tiempo estimado de lectura segÃºn la velocidad que elijas. El desglose tambiÃ©n ayuda a detectar capÃtulos vacÃos (un error tÃpico al generar el Ãndice).

6. Si el EPUB no abre

"No es un EPUB vÃ¡lido" casi siempre significa que el empaquetado estÃ¡ roto (el mimetype no va primero, falta container.xml), no el contenido. Pasa el archivo por Reparar EPUB y, si el Ãndice falla, por Arreglar Ãndice EPUB.

Bonus: automatÃzalo en tu pipeline

Si generas el libro desde Markdown, puedes convertir con Markdown a EPUB o usar la API REST de conversiÃ³n (documentada en e-ink.me/es/developers). Las comprobaciones visuales de arriba conviene hacerlas a mano al menos en la primera versiÃ³n.

Y para enviarlo: el botÃ³n Send to Kindle de E-Ink manda el archivo directamente a tu Kindle (1 crÃ©dito por envÃo, despuÃ©s de guardar tu direcciÃ³n @kindle.com y autorizar el remitente en Amazon).

Resumen

Vista previa e-ink: blanco y negro, 4 grises.
Metadatos: tÃtulo, autor, idioma.
Portada legible en grises.
Comprimir si pesa demasiado.
Contar palabras y revisar capÃtulos.

Y si te apetece un descanso sin salir del Kindle: games.e-ink.me/es tiene sudoku, nonogramas y buscaminas sin animaciones, pensados para tinta electrÃ³nica.

Reading a whole online programming book on a Kindle: from a table-of-contents URL to your device

Selenium39 — Fri, 02 Oct 2026 23:41:22 +0000

A lot of good technical books live on the web as a table-of-contents page with one HTML page per chapter. Free books, official language guides, long tutorial series, and documentation "books" built with mdBook, Sphinx or GitBook all follow this pattern. They read fine in a browser. On an e-reader they're a pain: you'd have to save every chapter by hand, stitch the files together, fix the order, and then get the result onto the device.

This post walks through a workflow that handles the whole thing in a few minutes with two features E-Ink (e-ink.me) added recently: Whole book mode and Send to Kindle.

Only do this with content you're allowed to keep a personal copy of: open-licensed books, docs under permissive licenses, your own writing, and so on. Respect each site's terms.

Why not just "print to PDF"?

PDF is a fixed page. A 6- or 7-inch e-ink screen has to zoom and pan through it, and code blocks become tiny. EPUB is reflowable: the reader picks the font size, long lines wrap, and the table of contents becomes real navigation. For anything you plan to read rather than print, EPUB wins.

The catch is that turning 40 web pages into one EPUB with a sane TOC is tedious work. That's the part to automate.

Step 1: find the table-of-contents page

You want the page that links to every chapter in reading order. Typical candidates:

the "Contents" or "Table of contents" page of an online book
the sidebar index page of an mdBook or Sphinx site (often the book's landing page)
the index page of a multi-part tutorial series

Pages that list chapters as plain links in order work best. A JavaScript-only menu that appears after a click is harder for any tool to parse.

Step 2: let the tool detect the chapters

On the E-Ink homepage the converter has three tabs: Single page, Multiple pages and Whole book. In Whole book mode:

Paste the table-of-contents URL.
Click Detect chapters. You get the book title and a chapter list ("N chapters detected").
Uncheck what you don't need: forewords, changelogs, "about this book" pages, index pages. Select all is there if you want everything.
The button shows the price before anything runs: 3 credits per chapter, with a cap badge for long books. New accounts get 10 free credits, so a short series fits in the free tier and longer books cost a few cents per chapter (pricing).
Confirm. Progress shows as done/total chapters. Chapters that fail are refunded automatically.

When it finishes you download the EPUB. If you close the dialog without saving, you can regenerate the same book for free within 24 hours, so a misclick doesn't cost you anything.

Trimming the chapter list is the most useful step here. Documentation books tend to include pages that make sense in a browser and are pure noise in a book (search pages, "edit this page" stubs, API index dumps). Removing them before conversion keeps the TOC clean and the cost down.

Step 3: push it to the Kindle without a cable

Amazon's Send to Kindle has accepted EPUB since 2022, and current Kindles open those files natively. E-Ink now has a Send to Kindle button, so you don't have to download the file and email it to yourself.

One-time setup:

Find your Kindle's email address (something@kindle.com). It's in Amazon's Manage Your Content and Devices â†’ Preferences â†’ Personal Document Settings.
In the same section, add E-Ink's sender address to the Approved Personal Document E-mail List. The Send to Kindle dialog has a "Copy sender address" button and a link to Amazon's settings.
Save your Kindle address in the E-Ink dashboard under Send to Kindle, so you don't have to type it again.

After that, hit Send to Kindle and the book shows up on the device a few minutes later, as long as it's on Wi-Fi. Each delivery costs 1 credit.

Step 4: check the result on the device

A few things are worth a quick look on the first book from a new site:

Code blocks. Long lines wrap on small screens. If a book is code-heavy, try landscape mode or a smaller font for those chapters.
Images and diagrams. They come through, but dense diagrams can be hard to read on a 6" screen. You can preview the EPUB in the browser first with the EPUB e-ink preview tool. It simulates Kindle and Kobo screen sizes in B&W or 4-level grayscale.
Title and author. Some sites put the site name in the page title, and that ends up on your Kindle shelf. The EPUB metadata editor fixes title, author, language and description locally in the browser before you send.

Automating the single-page part

If you prefer scripts, the regular web-to-EPUB conversion is also available as a REST API (POST /api/v1/convert/webpage, Bearer key, documented at e-ink.me/en/developers). Pass several URLs and they're merged into one EPUB. That works well for a cron job that bundles a weekly reading list. Whole-book detection with chapter selection is a UI feature for now.

A note on reading breaks

If you're working through a long technical book on an e-reader, short breaks work better on the same device than on a phone. There's a set of free browser puzzle games built for e-ink screens (Sudoku, Nonogram, Minesweeper and others, with no animations to smear the display) that run in the Kindle's experimental browser.

Summary

Find the table-of-contents page.
Use Whole book mode on e-ink.me and trim the chapter list.
Set up Send to Kindle once, then deliver with one click.
Preview and fix metadata if the book is going to sit on your shelf for a while.

It takes a few minutes instead of an afternoon of copy-pasting, and you end up reading the book on a screen that doesn't buzz.

Generating puzzles with exactly one solution: Sudoku, Nonogram and a daily seed, in plain JavaScript

Selenium39 — Mon, 28 Sep 2026 13:56:23 +0000

When I built a set of browser puzzle games meant to run on e-ink readers (E-Ink Games), one requirement shaped almost every piece of code: every puzzle must have exactly one solution. On a slow, paper-like screen nobody wants to guess and backtrack; the fun is pure deduction. That turned out to be a nice little algorithms problem, so here is a simplified version of how generators like these work, with code you can lift.

Why "exactly one solution" matters

A Sudoku or Nonogram with two valid solutions forces the player to guess at some point. Guessing on a phone is annoying. Guessing on an e-ink display, where every mistaken fill costs a visible refresh, is miserable. It also breaks the promise that "logic is always enough", which is the whole appeal of these puzzles.

So the generator pipeline is always:

Produce a random complete solution.
Remove information (clues) while a solver confirms the solution is still unique.
Stop when the target difficulty is reached.

The trick is step 2: you need a solver that can count solutions, and it needs to stop at 2.

Sudoku: fill, then dig

Step 1: a random full grid

Backtracking with shuffled candidates gives you a uniformly-ish random valid grid quickly:

function shuffle(a) {
  for (let i = a.length - 1; i > 0; i--) {
    const j = Math.floor(rand() * (i + 1));
    [a[i], a[j]] = [a[j], a[i]];
  }
  return a;
}

function canPlace(g, idx, n) {
  const r = Math.floor(idx / 9), c = idx % 9;
  const br = r - (r % 3), bc = c - (c % 3);
  for (let k = 0; k < 9; k++) {
    if (g[r * 9 + k] === n || g[k * 9 + c] === n) return false;
    if (g[(br + Math.floor(k / 3)) * 9 + bc + (k % 3)] === n) return false;
  }
  return true;
}

function fill(g, idx = 0) {
  if (idx === 81) return true;
  if (g[idx]) return fill(g, idx + 1);
  for (const n of shuffle([1,2,3,4,5,6,7,8,9])) {
    if (canPlace(g, idx, n)) {
      g[idx] = n;
      if (fill(g, idx + 1)) return true;
      g[idx] = 0;
    }
  }
  return false;
}

Step 2: count solutions, but stop at two

function countSolutions(g, limit = 2) {
  // pick the empty cell with the fewest candidates (MRV heuristic)
  let best = -1, bestCands = null;
  for (let i = 0; i < 81; i++) {
    if (g[i]) continue;
    const cands = [];
    for (let n = 1; n <= 9; n++) if (canPlace(g, i, n)) cands.push(n);
    if (cands.length === 0) return 0;
    if (!bestCands || cands.length < bestCands.length) { best = i; bestCands = cands; }
    if (cands.length === 1) break;
  }
  if (best === -1) return 1; // grid full
  let total = 0;
  for (const n of bestCands) {
    g[best] = n;
    total += countSolutions(g, limit - total);
    g[best] = 0;
    if (total >= limit) break;
  }
  return total;
}

The minimum-remaining-values heuristic is what keeps this fast enough to run on a Kindle's modest CPU. Without it, an Expert board with ~22 clues can take noticeably long to verify.

Step 3: dig holes

function makePuzzle(targetClues) {
  const solution = new Array(81).fill(0);
  fill(solution);
  const puzzle = solution.slice();
  for (const i of shuffle([...Array(81).keys()])) {
    if (81 - puzzle.filter(v => !v).length <= targetClues) break;
    const keep = puzzle[i];
    puzzle[i] = 0;
    if (countSolutions(puzzle.slice()) !== 1) puzzle[i] = keep; // put it back
  }
  return { puzzle, solution };
}

Clue count is a rough proxy for difficulty. In the live game, easier boards give around forty givens and Expert leaves just over twenty. A better difficulty metric is "which techniques does a human-style solver need" (naked singles only vs. pairs vs. X-wings), and that is a good next step if you want finer control.

Nonogram: the uniqueness problem is harder

A nonogram's clues are the run lengths of filled cells in each row and column. Generating a random picture is trivial; the problem is that most random pictures are ambiguous. Two different grids can share the same clues (the classic 2×2 checkerboard is the smallest example).

A practical approach:

Generate a random grid at a target fill density (around 50–60% keeps it interesting). Mirroring it gives a symmetric, more "picture-like" result.
Compute clues.
Run a line solver: repeatedly, for each row/column, enumerate all placements of its runs consistent with already-known cells, and mark cells that are filled (or empty) in every placement.
If line solving alone determines the whole grid, the puzzle is uniquely solvable by logic. If it stalls, regenerate.

// All placements of runs `clue` in a line of length n, consistent with known cells
function* placements(clue, n, known, pos = 0, i = 0, line = []) {
  if (i === clue.length) {
    const rest = Array(n - pos).fill(0);
    const full = line.concat(rest);
    if (full.every((v, k) => known[k] === -1 || known[k] === v)) yield full;
    return;
  }
  const remaining = clue.slice(i).reduce((a, b) => a + b, 0) + (clue.length - i - 1);
  for (let start = pos; start + remaining <= n; start++) {
    const seg = Array(start - pos).fill(0).concat(Array(clue[i]).fill(1));
    if (i < clue.length - 1) seg.push(0);
    const next = line.concat(seg);
    if (next.every((v, k) => known[k] === -1 || known[k] === v))
      yield* placements(clue, n, known, next.length, i + 1, next);
  }
}

Intersecting all placements per line and iterating until nothing changes is exactly what a human does ("overlap from both ends"), so "line-solvable" is a great definition of "fair". It is stricter than "unique" (some unique puzzles need lookahead), and that strictness is a feature for a casual game.

Boards in the game are 5×5, 10×10 and 15×15. For 15×15 the enumeration can explode on long lines with many short runs; caching placements per (clue, known-mask) keeps it manageable.

Daily puzzles without a server

Both the Wordle-style word game and the daily nonogram give every player worldwide the same puzzle on the same day, with no backend. The idea: derive a seed from the date, feed it to a small deterministic PRNG, and run the same generator.

function hashString(s) {
  let h = 2166136261 >>> 0;              // FNV-1a
  for (let i = 0; i < s.length; i++) {
    h ^= s.charCodeAt(i);
    h = Math.imul(h, 16777619);
  }
  return h >>> 0;
}

function mulberry32(a) {
  return function () {
    a |= 0; a = (a + 0x6D2B79F5) | 0;
    let t = Math.imul(a ^ (a >>> 15), 1 | a);
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

const today = new Date().toISOString().slice(0, 10); // pick one timezone convention!
let rand = mulberry32(hashString("nonogram:" + today));

Two gotchas:

Never use Math.random() anywhere in the generator path once you go deterministic, or players will get different boards.
Pick a timezone convention and stick to it, otherwise players on different sides of midnight disagree about which puzzle is "today".

Bonus: an unbeatable Tic-Tac-Toe

The Hard mode of the Tic-Tac-Toe game is plain minimax. With only 9 cells the full tree is tiny (< 550k nodes without pruning), so no alpha-beta or memoization is needed even on an e-reader. The best a human can do is a draw, which is a surprisingly fun challenge in itself.

Takeaways

Generate a full solution, remove clues, and verify uniqueness with a solver that stops at 2.
MRV makes Sudoku counting fast enough for weak hardware.
For nonograms, "solvable by line logic" is a better target than "unique".
Date-seeded PRNGs give you daily shared puzzles with zero backend.

If you want to see these generators in action, all ten games (Sudoku, Nonogram, Minesweeper, 2048, Word Daily and more) are free at games.e-ink.me, no account and no ads. They are designed for Kindle and BOOX browsers but work fine on a desktop too.

EPUB to Markdown: Getting Books Into Obsidian, Git and Your LLM Pipeline

Selenium39 — Thu, 24 Sep 2026 22:45:05 +0000

Ebooks are strangely locked away. The text is right there (an EPUB is literally a ZIP of XHTML files), yet it lives inside reader apps that don't talk to the rest of your tools. You can't grep it, diff it, link it from your notes, or chunk it for a retrieval pipeline without some glue.

Markdown is the glue. Once a book is a .md file, it drops into the plain-text ecosystem: Obsidian vaults, Notion imports, static-site generators, Git repos, and any script that eats text.

This post walks through converting an EPUB to Markdown in the browser, what survives the conversion, and a couple of small scripts for the most common next steps.

Why not just extract plain text?

You could unzip the EPUB and strip tags, or convert to TXT. That works for word-frequency experiments, but you lose the one thing that makes a book navigable: structure. Chapter titles, section headings, lists, block quotes, and links all flatten into an undifferentiated wall.

Markdown keeps that structure with almost no syntax overhead:

chapter and section titles become # headings
lists stay lists (nesting included)
links stay links
quotes keep their >
code blocks and tables survive

For humans, that means the file still reads like a book in a text editor. For machines, it means explicit hierarchy you can split on.

Converting in the browser

The iloveepub EPUB to Markdown converter does the whole thing client-side. You pick a file, each chapter is parsed and rebuilt as Markdown, a progress bar tracks it, and you download a single .md file. The book is never uploaded, which you can confirm yourself: open the Network tab in DevTools while it runs and you'll see zero upload requests. No account or API key is needed, and there's no rate limit.

Steps:

Open the converter and select your .epub.
Click Convert to Markdown.
Download the .md file.

That's genuinely it. There are no options to tune, which is a feature when you just want the text out.

What comes out (and what doesn't)

Carried over: headings (as # levels), bold and italics, links, lists including nested ones, block quotes, code blocks, tables, and horizontal rules. The rule of thumb is that anything the book marks up semantically survives; purely visual styling (fonts, colors, custom spacing) doesn't.

Images: each one becomes a standard reference like ![alt text](original-path), preserving alt text and the original path. The image files themselves aren't exported; the output is one self-contained text file. If you need the images too, unzip the EPUB separately and copy its image folder next to the .md file. The references keep the paths used inside the book, so a quick find-and-replace on the folder prefix is usually all it takes to make them resolve in your vault.

DRM-protected books can't be opened by any browser tool, so this is for DRM-free purchases, public-domain titles, and your own documents.

Next step #1: one note per chapter for Obsidian

Dropping a 400 KB single file into a vault works, but one note per chapter is nicer for linking and backlinks. Here's a small Python script that splits on the shallowest heading level that repeats, which is almost always the chapter level:

import re, sys, pathlib

src = pathlib.Path(sys.argv[1])
text = src.read_text(encoding="utf-8")

# Pick the shallowest heading level that appears more than once
# (so a single "# Book Title" at the top doesn't swallow everything)
levels = [len(m) for m in re.findall(r"^(#{1,6}) ", text, flags=re.M)]
if not levels:
    sys.exit("no headings found")
repeated = [lv for lv in sorted(set(levels)) if levels.count(lv) > 1]
top = "#" * (repeated[0] if repeated else min(levels))

parts = re.split(rf"^(?={re.escape(top)} )", text, flags=re.M)
out = src.with_suffix("")
out.mkdir(exist_ok=True)

count = 0
for i, part in enumerate(p for p in parts if p.strip()):
    count += 1
    first = part.splitlines()[0].lstrip("# ").strip() or f"part-{i}"
    slug = re.sub(r"[^\w\- ]", "", first)[:60].strip()
    (out / f"{i:02d} {slug}.md").write_text(part, encoding="utf-8")

print(f"wrote {count} files to {out}/")

Run it with python split_md.py my-book.md, then move the folder into your vault. The zero-padded prefix keeps chapters sorted in the file explorer.

Next step #2: chunking for RAG

If you're feeding books to a language model for Q&A, summaries, or retrieval, Markdown is about as LLM-friendly as a book gets: one clean file, explicit heading hierarchy, and no layout noise for the model to trip over.

Headings also make natural chunk boundaries. Rather than slicing every N tokens and cutting paragraphs in half, split on headings and carry the heading path as metadata:

import re

def chunk_markdown(md: str, max_chars: int = 4000):
    path, buf, chunks = [], [], []

    def flush():
        body = "\n".join(buf).strip()
        if body:
            for i in range(0, len(body), max_chars):
                chunks.append({"section": " > ".join(path), "text": body[i:i + max_chars]})
        buf.clear()

    for line in md.splitlines():
        m = re.match(r"^(#{1,6}) (.*)", line)
        if m:
            flush()
            depth = len(m.group(1))
            path[:] = path[: depth - 1] + [m.group(2).strip()]
        else:
            buf.append(line)
    flush()
    return chunks

Each chunk arrives with its context attached ("Part Two > Chapter 7 > The Harbor"), which tends to give a retriever (and the model reading the results) far more to work with than anonymous fixed-size windows. Swap the naive character split for a token-aware splitter if you need precise budgets.

Other things people do with it

Version a manuscript. Convert successive drafts and git diff them. Prose diffs are much easier to review in Markdown than in XHTML.
Publish excerpts. Most static-site generators (Hugo, Astro, Jekyll, Eleventy) take Markdown directly, so a public-domain book can become a website with a front-matter block.
Search your library. A folder of .md books plus ripgrep is a surprisingly good full-text search engine.
Import into Notion. The output is standard CommonMark-flavored Markdown, so Notion's Markdown import keeps headings, lists, and links intact.

Wrap-up

Books deserve to be first-class text, not blobs trapped in a reader app. Converting EPUB to Markdown is the shortest path from "file on disk" to "something my tools understand." Convert one book, split it, and see how differently you use it once it lives next to your notes.

Process EPUB files in the browser — no uploads

Selenium39 — Thu, 17 Sep 2026 16:31:15 +0000

EPUB files are ZIP-based books, so many useful operations can happen entirely in the browser. That means a reader can inspect metadata, validate a package, or prepare a file without sending their book to a server.

Why client-side processing matters

Books can contain personal notes, unpublished writing, reading history, or licensed material. A local-first workflow keeps the original file on the user’s device and reduces both privacy risk and infrastructure cost. It also works well for offline-capable web apps.

A typical implementation uses the File API and a ZIP reader:

const [file] = fileInput.files;
const bytes = await file.arrayBuffer();
const archive = await unzip(bytes); // use a maintained ZIP library
const container = await archive.text("META-INF/container.xml");

From there, the app can locate content.opf, read the manifest and spine, and offer a focused transformation. Keep processing in memory where possible, explain permissions clearly, and never upload the file unless the user explicitly chooses a remote feature.

A practical browser-local tool

I Love EPUB is a useful collection of browser-based EPUB tools for common tasks such as compressing, converting, and editing books. The local-processing approach is a good default: fast feedback, fewer data transfers, and a simpler privacy story.

For production apps, test large books, malformed archives, and mobile memory limits. Clear error messages and a visible “nothing uploaded” promise can make local-first EPUB workflows much easier to trust.

A web-to-EPUB pipeline: readable extract, chapter structure, Pandoc

Selenium39 — Sat, 29 Aug 2026 15:37:33 +0000

pandoc -f html -t epub3 https://example.com/post -o post.epub looks like a complete product. It is not. Pandoc is a typesetter. It will faithfully encode whatever tree you give it, including the cookie banner.

I run E-Ink, a small web-to-EPUB service. This is the pipeline underneath it, and why the interesting work is not the EPUB zip.

1. Fetch what a reader actually saw

A lot of the pages people want on a Kindle are JS-rendered docs, not static article HTML. A single GET of the URL returns a shell. You need a rendered DOM (we use Firecrawl for this), not wget. That already puts you in “this costs something” territory, which is why a free-forever scraper that also produces pretty EPUBs is usually lying about one of those adjectives.

Public pages only. No login cookies, no paywall punching. If the extract is empty, fail loud.

2. Extract the document, not the application

Readability-style extraction is the whole game. Keep title, byline, headings, lists, blockquotes, <pre><code>, figures + captions. Drop nav, footers, related rails, signup modals, comment widgets.

Two failure modes I still see weekly:

Under-extract. The article is a docs page whose “body” is a tabbed component. You get the first tab and a blank.
Over-extract. You kept the sidebar TOC as if it were chapter one.

Markdown is a good intermediate. It is diffable, previewable, and Pandoc eats it. If the Markdown looks wrong, do not bother emitting EPUB. We show a Markdown preview in the UI for exactly this reason.

3. Headings → spine, not a wall of `<p>`

EPUB readers live and die by the nav document. A 8,000-word essay with one <h1> and no <h2> is a brick. A docs page that uses <h3> for everything produces a TOC that is either empty or 90 entries deep.

Normalize heading levels against the document you actually got, not against the HTML5 spec the CMS ignored. Promote or demote so the spine has a usable chapter list. This is boring string work and it is more important than your CSS.

Images: resolve src / srcset / data-src, download, cap dimensions, rewrite to package-relative paths. Lazy-load placeholders are the number one “why is my ebook a gray box” bug.

4. Pandoc for EPUB3, not for fetching

Once you have a clean Markdown document plus a media folder, Pandoc is the right tool:

pandoc article.md \
  --from markdown \
  --to epub3 \
  --epub-title="..." \
  --output article.epub

Let Pandoc write the zip, the nav, the OPF. Do not hand-roll EPUB unless you enjoy debugging mimetype-must-be-first-and-uncompressed for the tenth time.

Output formats beyond EPUB are the same document, different writer: PDF, Markdown, or a second pass to MOBI for older Kindles. Newer Kindles take EPUB natively. Do not make MOBI the default in 2026.

The public API is that pipeline with a credit meter

Same steps, HTTP in front. Bearer token, one URL (or several), a format:

curl -X POST https://e-ink.me/api/v1/convert/webpage \
  -H "Authorization: Bearer eink_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://e-ink.me", "format": "epub"}' \
  -o article.epub

Webpage → ebook is 3 credits per URL. File conversion, translation, TTS, and mind maps are separate endpoints on the same key. Docs, OpenAPI, llms.txt, and an MCP manifest live at e-ink.me/en/developers. If you want the same calls inside Cursor or Claude Code, there is a skill at github.com/Selenium39/e-ink-skill — npx e-ink-skill and EINK_API_KEY.

CSS and the e-ink constraints

Ship almost no CSS. E-readers ignore half of it and fight the other half. Relative font sizes, default margins, break-inside: avoid on pre/code and figures. No position: fixed. No dark-mode media queries that assume an emissive screen. Code blocks need wrapping or they clip on a 6-inch Kindle; that is a content problem, not a theme problem.

If you are tempted to embed a webfont: don't, unless you have tested the file on a 2018 Kobo. The reader already has a font. Your job is structure.

What we refuse to do

No session cookies. If the page needs a login, it is not a public article.
No “print the whole SPA as screenshots.” That is a PDF of a website, not a book.
No storing the source file as a convenience cache. Uploads live long enough to produce the output, then they are deleted. The in-browser readers do not upload at all.

I did not invent readable extract or Pandoc. I glued them so I could stop sending navbar novels to a Kobo. If you are building your own pipeline, steal the shape: render → extract → structure → package. If you just want the file, paste a URL on the site. New accounts get free credits.

Questions / broken extracts: openminimax@gmail.com. I am Selenium39.