doc2md-action
Turns PDFs, Office files and scans into Markdown — as a GitHub Action on every push, or in your browser with nothing uploaded.
- 01Per-format routing
- 02OCR fallback
- 03Browser version
- 04Batch in the browser
- 05Token trimming
- 06Traceability and failures
Architecture Overview
AI tools and code search cannot read a PDF or a spreadsheet — they read text. This does the reading and leaves behind Markdown that anyone, or anything, can open. Point the Action at a folder of documents and it converts them on every push; or open the browser version, drop files straight in, and get the same Markdown back without committing anything anywhere.
How it works
Core mechanics, failure recovery paths, and system design decisions.
Per-format routing
PDFs give up their text per page; Word, PowerPoint and HTML become headings, paragraphs and lists; Excel and CSV become one Markdown table per sheet. Legacy .doc, .xls and .ppt go through LibreOffice into the modern format first.
OCR fallback
A PDF page holding almost no extractable text is treated as a scan, rendered at the configured DPI and read with Tesseract. Whichever version has more text wins, so a page that did have text loses nothing to the attempt.
Browser version
The same conversion runs entirely in the tab, served from GitHub Pages. Files are read with the File API and never leave the machine — there is no upload endpoint, because a static host has nothing to upload to.
Batch in the browser
A dropped folder or .zip converts at once in a worker pool sized from the machine's core count, with a matching pool of OCR workers. Results are held as Blobs so a big batch never fills the JS heap, and folder structure survives into the downloaded zip.
Token trimming
Compact mode drops blank lines and the headers and footers repeated on every page, and the run reports total tokens and the percentage saved.
Traceability and failures
Every output file opens with a header naming the document it came from, and a manifest records page counts and whether OCR was needed. One unreadable document is counted as failed and everything else still converts, unless you ask the job to fail on error.
Engineering Highlights
- •Scanned pages picked up by OCR without being asked
- •A browser version that converts locally, with nothing uploaded
- •Whole folders and zips at once, on as many cores as the machine has
- •One merged file when you want to paste a whole document set into a model
- •A header on every output and a manifest, so any sentence traces back to its source