pdf-html

Early-stage geometry-first PDF → HTML converter for text-based PDFs — verbatim text, source typography, zero images.

One command in. One elegant, dependency-free HTML file out.

🎯 What it does

pdf-html is an early-stage, geometry-first PDF-to-HTML converter for text-based PDFs. It rebuilds the document as a single self-contained HTML5 file that mirrors the source document's look and structure:

• ✅ Best for: text-based PDFs with real text layers, headings, lists, tables, and multi-column layouts

• ⚠️ Not a universal OCR-first converter: scanned/image-heavy PDFs still need an OCR pre-pass or a dedicated workflow

• 🏷️ Heading hierarchy — font-size tiers become real <h1>–<h6>

• 🎨 Typography & color — the page CSS is derived from the document's own fonts, sizes, and palette

• 📊 Tables — ruled tables are rebuilt as real <table> elements, including lists inside cells and rows that continue across page breaks

• 📝 Lists — bullets and numbered items become nested <ul>/<ol> (indent decides nesting)

• 🧭 Reading order — multi-column layouts are re-linearized column by column

• ✂️ Page furniture — repeated running headers/footers and page numbers are stripped

• 🔒 Text is verbatim — never summarized, reworded, or reordered within a block

• 🚫 No images, ever — image content is dropped by design; text alone carries the document

🧭 Early-stage scope

This is an early-stage, geometry-first conversion tool for text-based PDFs. It is designed to be reliable and deterministic where the PDF has a usable text layer, but it is not a universal OCR-first converter for scanned documents, forms, or arbitrary image-heavy PDFs.

What it does well

• text-based PDFs with real text layers
• styled HTML with verbatim text
• heading hierarchy, lists, and multi-column layout reconstruction
• ruled table reconstruction with cell-aware content flow

What it does not yet do well

• OCR and scanned-document support are planned as separate, opt-in paths
• arbitrary image-heavy PDFs or forms with weak text layers
• pixel-perfect visual reconstruction of every layout edge case

⚡ Quick start

# install from PyPI (Python 3.10+)
pip install pdf-html
# or: uv pip install pdf-html

# convert
pdf-html report.pdf -o report.html

# open report.html in any browser — no external assets needed

If you are working from a cloned repository instead of the published package, install the local checkout with pip install -e . or uv pip install -e ..

🖥️ CLI reference

pdf-html INPUT.pdf -o out.html [--extractor pymupdf|pdftotext]
    [--style auto|default] [--paginate] [--no-tables] [--no-callouts]
    [--keep-headers] [--allow-scanned]

🏗️ Architecture

A deterministic pipeline — every stage is a small, pure, individually testable module:

---
config:
  layout: elk
  theme: neutral
---
flowchart LR
    subgraph S1["📥 1 · Extract"]
        direction TB
        PDF@{ shape: doc, label: "📄 PDF" }
        EX@{ shape: rect, label: "Extractor<br/>spans + font metadata" }
        PDF --> EX
    end
    subgraph S2["🧹 2 · Clean &amp; Profile"]
        direction TB
        HF@{ shape: rect, label: "Header/Footer<br/>stripping" }
        SP@{ shape: hex, label: "Style Profiler<br/>body size · h1–h6 · palette" }
        HF --> SP
    end
    subgraph S3["🧭 3 · Layout"]
        direction TB
        RO@{ shape: rect, label: "Reading Order<br/>column clustering" }
        TR@{ shape: fr-rect, label: "Table Reconstructor<br/>per-cell pipeline" }
    end
    subgraph S4["🏗️ 4 · Structure"]
        direction TB
        SD@{ shape: div-rect, label: "Structure Detector<br/>headings · paragraphs · lists" }
        LP@{ shape: rect, label: "List Parser<br/>nested ul/ol" }
        AST@{ shape: bow-rect, label: "AST<br/>Document → Page → Blocks" }
        SD --> LP --> AST
    end
    subgraph S5["🎨 5 · Render"]
        direction TB
        RN@{ shape: rect, label: "Renderer<br/>semantic HTML5 + inline CSS" }
        OUT@{ shape: tag-doc, label: "🌐 out.html" }
        RN --> OUT
    end
    EX --> HF
    SP --> RO
    SP --> TR
    RO --> SD
    TR --> SD
    AST --> RN

📊 Table reconstruction highlights

The hardest part of PDF → HTML is tables. pdf-html:

1. 🔍 Detects ruled tables geometrically (PyMuPDF find_tables()) at extraction time
2. 📌 Assigns the page's styled spans to cells by bounding box — inline bold/color/size survive
3. 🔄 Runs the normal line → paragraph → list pipeline inside every cell, so bullets in cells become real nested lists
4. 🧵 Merges rows that continue across page breaks (empty-first-cell fragments) back into one row — even resuming mid-list-item
5. 🏷️ Promotes a bold-only first row to a <th> header row

🧭 Design principles

⚖️ How it compares

Every PDF converter picks a trade-off. pdf-html optimizes for semantic, reflowable, styled HTML with a verbatim-text guarantee — a square none of the established tools occupy:

When to choose pdf-html — you want a readable, reflowable document that still looks like the original, produced offline, reproducibly, with text you can trust character-for-character (text-based PDFs, tables included, even across page breaks).

When to choose something else — you need pixel-perfect visual replicas (pdf2htmlEX), OCR-heavy scanned document conversion (marker, docling), or RAG-oriented element JSON (unstructured).

🧪 Testing

56 tests cover every pipeline stage plus end-to-end CLI runs over deterministic fixture PDFs (report, two-column paper, slide deck, brochure, ruled table):

uv sync                                        # dev deps (pytest, reportlab)
uv run pytest                                  # run the suite
uv run python tests/fixtures/make_fixtures.py  # regenerate fixture PDFs

Verbatim-ness is asserted mechanically: every source string drawn into a fixture must appear in the rendered HTML.

📁 Project structure

pdf-html/
├── src/pdf_html/
│   ├── cli.py                  # argparse CLI → pipeline → HTML
│   ├── extractor.py            # PyMuPDF span + table-region extraction
│   ├── header_footer.py        # repeated page-furniture stripping
│   ├── style_profiler.py       # font-size histogram → style profile
│   ├── reading_order.py        # column clustering & span ordering
│   ├── table_reconstructor.py  # cell assignment, per-cell pipeline, row merging
│   ├── structure.py            # heading / paragraph / list classification
│   ├── list_parser.py          # nested list folding
│   ├── ast.py                  # typed document model
│   └── renderer.py             # semantic HTML5 + derived CSS
├── tests/                      # 56 tests + deterministic PDF fixtures
├── README.md
└── TUTORIAL.md                 # step-by-step usage guide

🛣️ Roadmap

• Ruled-table reconstruction with cross-page row merging
• Column-aware reading order with card-grid detection
• Repeated header/footer stripping
• Borderless-table detection (whitespace-gap heuristic)
• Callout/aside detection (--no-callouts flag already reserved)
• Dependency-free pdftotext fallback extractor
• colspan/rowspan from merged-cell geometry

🤝 Contributing

Contributions welcome! Ground rules:

• 🐍 Python 3.10+, type hints throughout
• 📦 PyMuPDF is the only hard runtime dependency
• 🧩 Keep heuristics small, pure, and individually testable; thresholds as named constants
• ✅ One feature per commit (feat|fix|docs|refactor|chore: ...); update README/TUTORIAL with any user-facing change
• 🧪 uv run pytest must stay green — fixtures are the contract

🚀 Releases

This project is intentionally published as an early-stage v0.x tool: the core pipeline is solid for text-based PDFs, but it is not a universal PDF converter for scanned pages, forms, or OCR-heavy corpora.

# 1. bump version in pyproject.toml
uv build        # 2. artifacts land in dist/
uv publish      # 3. push to PyPI (or twine upload dist/*)

📄 License

MIT — see pyproject.toml.