pdf2htmlEX

Last reviewed Sep 13, 2026 · 792 words

A 40-page PDF run through pdf2htmlEX with default flags comes out as a single HTML file several times the size of the original, because every font is embedded as a data URI and every page is absolutely positioned to the pixel. That is the tool working as designed: it produces a browser-readable page that is visually indistinguishable from the PDF, text selectable, no plugin, no JavaScript viewer. It is a converter you run once per document, not a service you keep running, and the decision to use it comes down to whether pixel-exact fidelity is worth files that heavy.

What it is, and what it is not

pdf2htmlEX (5,600 stars, GPL-3.0, first released 2013) is a command-line tool built on Poppler and FontForge. It reads a PDF, extracts glyphs into web fonts, and writes HTML plus CSS that reproduce the layout exactly: columns, tables, footnotes, rotated text, all of it. There is no web UI, no upload page, no database. The original author archived the project years ago and a community group now maintains it, which is why the working repository lives under the pdf2htmlEX organisation rather than the original name.

If what you want is a tool to split, merge, OCR, or compress PDFs through a browser, that is Stirling PDF, and it is the bigger and more general project. If you want to read a library of ebooks in a browser, Kavita or Calibre-Web render PDFs as pages without converting anything. pdf2htmlEX is for the narrower case: you have documents that must be published as real web pages, with the layout preserved, on a static site or an intranet.

Running it from Docker without installing FontForge

The dependency chain is the hard part of a native install, which is why nearly everyone uses the container:

docker run --rm -v "$PWD":/pdf -w /pdf pdf2htmlex/pdf2htmlex:0.18.8.rc2-master-20200820-ubuntu-20.04-x86_64 \
  --zoom 1.3 --embed-font 1 --dest-dir out manual.pdf

Pin the tag; the image tags encode the Poppler build they were made against and the latest tag has not always pointed where you expect. The container needs around 512 MB of RAM for typical documents and more for anything with hundreds of pages of vector graphics. Batch conversion is a shell loop; there is nothing to daemonise.

The flags that decide file size

Three options change output size by an order of magnitude:

--embed-font 0 writes fonts as separate .woff files instead of base64 inside the HTML. For a site publishing many documents from the same source (the same corporate font set), this lets browsers cache fonts across documents and typically halves the per-page payload.

--split-pages 1 with --page-filename emits one file per page and a small loader, so a reader opening a 300-page manual downloads one page, not 300. This is the single most important flag for anything longer than a pamphlet.

--bg-format svg or jpg controls how non-text page content (images, vector art) is rasterised. PNG is the default and is lossless and huge; jpg at the default quality cuts image-heavy documents dramatically at a fidelity cost you will usually not notice on screen.

--process-outline 1 keeps the PDF's bookmark tree as a navigable sidebar, which is the difference between a converted manual you can use and one you scroll through.

Where fidelity turns into a problem

Because every character is positioned absolutely, the output does not reflow. On a phone it is a shrunken page you pinch-zoom, exactly as the PDF would be. Screen readers cope worse than with a semantic HTML page, since the reading order is geometric rather than structural. Search engines index the text fine, but the pages carry no headings and no meaning beyond the words. If the goal is accessible, responsive content, convert to real HTML by hand or with a structural tool, and keep pdf2htmlEX for archival and for documents whose layout is the content: forms, sheet music, annotated diagrams, scanned typography.

What I'd do

Keep pdf2htmlEX in a script, not a stack. For a collection of manuals or papers I want browsable on my own static site, I run the container in a loop with --split-pages 1 --embed-font 0 --bg-format jpg --process-outline 1, drop the output directories into the site's content folder, and let the web server serve them as plain files. For everything else PDF-shaped in a homelab, Stirling PDF is the tool to install first; pdf2htmlEX earns its place only when the PDF has to become a web page and look exactly like itself doing it.