feat: HTML + Markdown output formats (closes #6, builds on #8)

[ahnafnafee]

Summary

Closes #6 by adding HTML and Markdown as alongside-PDF output formats. Builds on @milahu's draft PR #8 — milahu's seven commits are preserved at their original SHAs at the branch base, with Co-authored-by trailers on the relocated logic.

What you can now do

# Auto-named per format
uv run local-llm-pdf-ocr scan.pdf --format html      # → scan_ocr.html
uv run local-llm-pdf-ocr scan.pdf --format md        # → scan_ocr.md

# Or pick by extension
uv run local-llm-pdf-ocr scan.pdf out.html
uv run local-llm-pdf-ocr scan.pdf notes.md

# HTML with dark-mode page inversion (opt-in)
uv run local-llm-pdf-ocr scan.pdf --format html --html-invert-dark

# Server: same, via the /process form field
curl -F file=@scan.pdf -F client_id=x -F format=html http://localhost:8000/process

The web UI (server.py) gets a small format dropdown beneath the upload zone.

What changed

Architecture

• src/pdf_ocr/core/html.py (new) — HTMLHandler with PDF and image input support (PR add output format HTML #8 only handled images), in-memory StringIO build, base64-inlined page images so the file is self-contained. Supports three sizing modes (scaled default, letter-spacing, full-height) and an opt-in invert_dark flag that injects filter: invert() hue-rotate(180deg) under prefers-color-scheme: dark.
• src/pdf_ocr/core/markdown.py (new) — MarkdownHandler: # OCR output header, ## Page N per page, one block per non-empty box in reading order. No paragraph-break heuristic (multi-column layouts break gap-based heuristics).
• src/pdf_ocr/core/_layout.py (new) — extracted is_full_page_fallback and split_multi_line_bbox helpers shared by every writer. Both PDF and HTML now route the aligner's [0,0,1,1]+\n fallback bbox identically, and split \n-joined visual lines into per-line sub-spans.
• src/pdf_ocr/output.py (new) — resolve_output_writer, media_type_for, suffix_for_format, format_from_path, SUPPORTED_FORMATS. Single source of truth for format dispatch; CLI and server both consume it.
• src/pdf_ocr/cli.py — adds --format {pdf,html,md} with extension-wins precedence, --html-invert-dark opt-in flag; passes the dispatched writer to OCRPipeline(output_writer=…). Also reverts PR add output format HTML #8's raise; sys.exit(1) regression in main().
• src/pdf_ocr/server.py — adds format: str = Form("pdf") to /process; wires Content-Type and download filename through media_type_for/suffix_for_format. Validates format and returns 400 on unsupported values.

--html-invert-dark flag (addresses PR feedback)

Added in response to @milahu's feedback about dark-mode page inversion. The CSS filter: invert() hue-rotate(180deg) on div.page is useful for reading scanned white-background documents at night, but is now opt-in since most PDF readers and browsers do not invert scanned images by default.

• HTMLHandler(invert_dark=True) injects an additional @media (prefers-color-scheme: dark) block
• CLI: --html-invert-dark
• resolve_output_writer(html_invert_dark=True) passes it through
• Example output: examples/output_digital_invert_dark.html

Alignment quality — scaled default

The HTML invisible-text overlay defaults to scaled mode — font shrinks to fit both bbox dimensions, staying legible at any zoom level. Two alternative modes (letter-spacing, full-height) are available via HTMLHandler(mode=…) / --html-mode.

PR #8 cleanup

Issue	Resolution
_embed_structured_text_html raised NotImplementedError for PDF inputs	Fixed — HTMLHandler rasterizes per page like PDFHandler
Stray print(f"output_ext: ...") debug statement	Removed
Multiple # TODO remove blocks of unreachable code	Removed
raise; sys.exit(1) in cli.py	Reverted
HTML logic embedded in PDFHandler	Relocated to core/html.py per author's recommendation

Tests

113 new tests, all on the fast tier (no LLM, no Surya):

• test_layout.py — 14 tests: full-page-fallback detection, multi-line bbox split
• test_html_handler.py — 15 tests: doctype + title, base64 inline, all sizing modes, full-page fallback, multi-line split, edge cases
• test_markdown_handler.py — 7 tests: structure, page order, reading order, empty-box skip
• test_output_dispatch.py — 28 tests: extension inference, suffix/media-type lookup, writer resolution
• test_cli.py — 9 tests: resolve_output_path precedence, --format parser
• test_server.py — 8 tests: format dispatch, download naming, error handling

Total suite: 294 tests passing (271 fast + 23 slow).

Documentation

• README: --html-invert-dark in the CLI options table and examples section
• CLAUDE.md: updated commands, HTMLHandler docstring with invert_dark parameter

Authorship preservation

milahu's seven commits (f775df5…10078d8) remain at their original SHAs at the branch base — no rebase, squash, amend, or force-push. Cleanup commits on top use Co-authored-by: Milan Huth <milahu@milahu.duckdns.org> wherever the new code derives from theirs.

Test plan

• All 294 tests pass (uv run pytest)
• CLI --help shows --html-invert-dark
• Without flag: no filter: invert() in HTML output
• With --html-invert-dark: filter: invert() hue-rotate(180deg) present under @media (prefers-color-scheme: dark)
• All example outputs regenerated against current code

[ahnafnafee]

@milahu Do the latest changes satisfy your expected output?

[milahu]

the default should be html_mode="scaled"
html_mode="letter-spacing" can make the text hard to read
when letters overlap with a negative letter-spacing

with html_mode="scaled"
at least i can zoom in to read the text

[milahu]

this comment is not helpful in the HTML output
it should be only in the python source

[milahu]

by default, it should use external image files from HTML
and there should be a CLI option
to enable embedding base64-encoded images into HTML
something like --html-embed-images or --html-inline-images

why?

• base64 encoding increases the file size by 35%, which is not wanted in most cases
• the image files exist as input files as one image per page
  • exception: when the input is a PDF file (or TIFF file) with multiple pages, then it is not possible to use the input file as image source in HTML. then each page image should be stored side by side with the output HTML file, only with a different file extension, for example some-page.html and some-page.jpg

[ahnafnafee]

External images should be default now

[milahu]

this fails for window.devicePixelRatio != 1
(when then display manager zoom level is not 100%)

window.innerWidth = document.body.clientWidth + scrollbarWidth

clientWidth - 1 to account for rounding errors
otherwise i still see a horizontal scrollbar
(my desktop zoom is 150%)

simplified function

(function(){
  var px = document.body.clientWidth - 1;
  for (const p of document.querySelectorAll('div.page')) {
    var w = parseFloat(p.style.getPropertyValue('--page-w'));
    if (!isFinite(w) || w <= 0 || w <= px) continue;
    p.style.width = px + 'px';
  }  
})();

[milahu]

darkreader does not invert images...

in my code i have this style
which just works, no "glyph outlines"

@media (prefers-color-scheme: dark) {
  div.page {
    filter: invert() hue-rotate(180deg);
  }
}

the hue-rotate(180deg) is needed
to convert darkblue to lightblue (instead of yellow)

"no darkmode" is also a stupid limitation of chrome's PDF reader
which makes it impossible for me to read PDF documents at night

[ahnafnafee]

I think this could be passed in as a CLI optional parameter instead of being the default

[milahu]

this is a special case, because we have images of text

the darkreader extension does not invert images, because darkreader does not know the difference between "images of text" and "images of cats", because there is no magic style class like img.imageoftext.lightmode, so i need the stylebot extension to invert images of text...

with the principle of least surprise, i would expect that when i set my display manager's color theme to dark (@media (prefers-color-scheme: dark)) then that should also invert images of text

in short, this should be default on, with an option to turn it off

no magic style class like img.imageoftext.lightmode

some book authors follow the bad taste of having some pages inverted (white text on black background) (example with L=0.02), so we could compute the lightness of each page (example output), to ensure that in our dark mode, the originally dark pages are not inverted, so all pages are dark. books can also have pages with an average lightness near 50% (gray) (example with L=0.35), so pages should be inverted only above some threshold, maybe 0.7 by default

[ahnafnafee]

Most tools (PDF readers, browsers) do not invert scanned page images by default, so automatically inverting them could be surprising to many users. I believe allowing it to be opt-in CLI flag would allow more customization for the end user.

[ahnafnafee]

I've added it as an opt-in CLI flag in the latest push (1d13516).

Usage:

uv run local-llm-pdf-ocr input.pdf --format html --html-invert-dark

This adds the following CSS block to the generated HTML, which activates only when the browser/OS is in dark mode:

@media (prefers-color-scheme: dark) {
  div.page {
    filter: invert() hue-rotate(180deg);
  }
}

Without --html-invert-dark, the page image renders as-is in all colour schemes (just the body background and outline adjust for dark mode). This keeps the default behaviour unsurprising for users with scanned colour documents or photos, while making it easy to opt in for the white-background-at-night use case you described.

I also generated an example with the flag applied: examples/output_digital_invert_dark.html — you can download it and test in your browser with dark mode enabled. The hue-rotate(180deg) handles the dark-blue → light-blue remapping you mentioned.

[milahu]

for single-page input files, there should be no _p1 suffix

so...

        rasterized_pages = self._rasterize_pages(input_path, dpi)
        for page_num, img_bytes, w, h in rasterized_pages:
            if len(rasterized_pages) == 1:
                sidecar_name = f"{out_stem}.jpg"
            else:
                sidecar_name = f"{out_stem}_p{page_num + 1}.jpg"

[milahu]

have you tested this with multi-page input files?
are the pages rendered properly, like in a PDF reader?

if one page has less width than other pages
it should be centered horizontally with

body {
  text-align: center;
}

or

div.page {
  margin: auto;
}

[ahnafnafee]

I will test this out and report back

[milahu]

nitpick: page_num + 1 should be zero-padded
so the image files are always sorted correctly

        rasterized = list(self._rasterize_pages(input_path, dpi))
        pnw = len(str(len(rasterized))) # page number width
        for page_num, img_bytes, w, h in rasterized:
            if len(rasterized) == 1:
                sidecar_name = f"{out_stem}.jpg"
            else:
                sidecar_name = f"{out_stem}_p{str(page_num + 1).zfill(pnw)}.jpg"

nitpick:
page_num should be renamed to page_idx
(1-based versus 0-based)

---

out of scope:
ideally we should avoid
list(self._rasterize_pages(input_path, dpi))
currently we need that only for len(rasterized)
but that forces to buffer the whole input in memory
which fails on large inputs or low memory...
ideally, the whole pipeline should be streaming

related: streaming PDF writer

• add PDF stream writer pymupdf/PyMuPDF#4968

[milahu]

all examples/*.html still have the old version

$ rg -F 'var px = window.innerWidth' examples/ | wc -l
5

$ rg -F 'var px = document.body.clientWidth' examples/ | wc -l
0