I do a lot of backend document (docx file) generation work, and updating our templates and backend code is one of my least favorite development tasks. Cryptic errors, minute-plus rebuild loops. I’d much prefer building these reports in JS rendered HTML (e.g., Vue or React), but existing HTML-to-docx libraries in the OSS ecosystem don't produce output that's actually valid, editable Word structure.
I'd had good luck applying Karpathy's Autoresearch pattern (agent runs iterations against an objective score, keeps what improves, discards what doesn't) to a couple of other problems, and figured OOXML fidelity was a good fit.
The Autoresearch process goes like this: render HTML and take a screenshot, use dom-docx to convert to docx, rasterize the docx file with LibreOffice and take another screenshot, score the browser HTML screenshot vs LibreOffice screenshot and measure layout fidelity + editability + speed as a quality metric, feed score back in, and repeat to drive higher fidelity within the constraints of editability and performance. It’s a beautiful thing to watch.
Burned some tokens and ran that loop against 37 real-world HTML patterns such as nested lists, tables, flex layouts and blockquotes (stuff that often breaks converters) and "brute forced" my way to what I hope is a high-fidelity HTML to docx converter.
A few things about where it landed:
- Native OOXML output, real Word structure, not a screenshot or a 1x1 table pretending to be a document
- Works in Node, in the browser (no Playwright needed for the default path), and as a CLI (npx dom-docx input.html -o output.docx)
- MIT licensed
- Full benchmark methodology + results vs the established OSS alternatives: https://github.com/floodtide/dom-docx/blob/main/docs/BENCHMA...
Live demo if you want to test HTML conversion in the browser: https://dom-docx.com
Happy to answer anything about the scoring loop or anything else.
PS: This is the first thing I've open sourced and I'm excited to see where it leads!
That's an interesting approach. I'm concerned about the use of LibreOffice as your source of truth. Would it be possible to swap out LibreOffice for actual MS Word in this workflow? This also could reveal some libreoffice rendering bugs/edge cases that are worth filing bugs over.
I don’t have MS word installed on my development machine, so I haven’t done much testing with Word, but that does sound like a good idea to run the suite using Word. For what it’s worth I did not notice any issues with LibreOffice, even after running many iterations and tests.
I would add a +1 for testing w/ Word - the official Office suite runs some validation where only Word will show a "broken file" popup, even when nothing else does.
In our case, clients use only real Word, so any machine-generated/mutated files (excel/ppt as well) need a pass through the real office executable.
I spent two days last week trying to figure out why a docx file I was generating with python-docx looked fine in libreoffice but would not open in word. it was just some text with a circle overlaid on it, but word is a lot fussier about the xml structure of the document than libreoffice is. finally had to create the same structure directly in msword and have claude examine the two files for differences.
Sounds to good to be true, but it works for the given examples!
What is the scope though? It produces garbage with larger documents with tables and figures. For example this large document, even with removed menu and headings: https://docs.redhat.com/en/documentation/red_hat_enterprise_...
All of the suite test cases are small fragments of HTML to test specific things, so I probably do need a way to test bigger documents. Thanks for the feedback. I’ll add that to the to-do list.
Ok, I dug into the Red Hat doc. It’s a great example and it uncovered a few real shortcomings.
A couple of things about this scenario:
First, the page relies on stylesheets, so you need styleSource: "computed", either Playwright on Node, or run in the browser with the content already rendered.
Second, dom-docx doesn’t fetch remote images itself. The caller supplies an imageResolver (e.g. a fetch callback), which keeps security, timeouts, host allowlists, etc. under caller control: https://dom-docx.com/learn#image-resolver
- oversized images not scaling down to the printable page width
- OS dark theme (prefers-color-scheme: dark) leaking near-white computed text colors into Word on the browser path
I also added an ad-hoc repo script that loads a live URL, takes a CSS selector, and converts with Playwright (tools/try-url.ts). I used it on the RHEL page and got a pretty decent 200+ page doc. Some tables still look wrong — I’ll dig into those next.
Interesting but how is an "autoresearch loop" different than creating a spec and X number of testcases and letting an agent run against these testcases and the spec?
This is very cool and thanks for sharing the workflow, buuuuuut... Could you please rewrite the README in your own words? If not for this comment, I would have just flagged this submission without looking into it further, because no matter how useful the premise is, it feels like one of the millions “I’ve burnt a bunch of tokens and thrown the result on GitHub” kinda projects you see nowadays. Clearly that’s not the case here, but an LLM-generated README really does your project a disservice.
Very interesting approach. I am having trouble with page breaks (documentation says they work, but demo pages dont) etc. For the invoicing example this would require table breaks/overflows into subsequent pages in a real application and I am currently evaluating going with model->PDF or model->DOCX
Do you have any approach in this regard that works ?
I tested this, but it seems like it regressed somehow. It may not be working in the browser side use case right now. I'll have to look at it later this evening. I created a GH issue to keep it on the radar: https://github.com/floodtide/dom-docx/issues/5
Could you update the GH issue with a bit more information about your specific use case?
Just adding, since I don't see it mentioned in the readme, that its written in Typescript. That's what makes this interesting. I imagine Pandoc can do this but its not Typescript (its Haskell).
Thanks, and just to mention, I’ve had awesome results using Autoresearch loops on other things like SQL performance.
Prompt example:
You are a SQL performance researcher. Run the following SQL query to establish a baseline, then come up with hypotheses to improve performance. Score each result and run 5 iterations. Avoid any regressions, each result must contain the exact same rows and columns.
Also works wonderful for generating AI scripts, goal being increasing the elo rating after a tournament run. Also having deep and shallow tests save a lot of time. Deep tests are run sparingly while shallow tests are run after each change.
I have done something similar for PPTX, keeping the fidility intact was really challenging with computed values & OOXML counterparts and again challanges with different XML implementations like that of MS & Libre..
Broken printing is a failure/intention of website developers. It’s very easy to define print styles with a `@media print {…}` CSS query. Few sites use it.
I did everything with the Cursor $20 plan and the Claude Code $20 plan, so in this particular case it wasn’t actually that many tokens. This was over the course of about four weeks of weekend and evening work.
Since HTML is so rich and the DX is amazing these days, I wish HTML file sharing for the document use case (and using the browser as a client) was widely accepted, it’s another problem/opportunity I’ve pondered a lot.
Hey HN, author here.
I do a lot of backend document (docx file) generation work, and updating our templates and backend code is one of my least favorite development tasks. Cryptic errors, minute-plus rebuild loops. I’d much prefer building these reports in JS rendered HTML (e.g., Vue or React), but existing HTML-to-docx libraries in the OSS ecosystem don't produce output that's actually valid, editable Word structure.
I'd had good luck applying Karpathy's Autoresearch pattern (agent runs iterations against an objective score, keeps what improves, discards what doesn't) to a couple of other problems, and figured OOXML fidelity was a good fit.
The Autoresearch process goes like this: render HTML and take a screenshot, use dom-docx to convert to docx, rasterize the docx file with LibreOffice and take another screenshot, score the browser HTML screenshot vs LibreOffice screenshot and measure layout fidelity + editability + speed as a quality metric, feed score back in, and repeat to drive higher fidelity within the constraints of editability and performance. It’s a beautiful thing to watch.
Burned some tokens and ran that loop against 37 real-world HTML patterns such as nested lists, tables, flex layouts and blockquotes (stuff that often breaks converters) and "brute forced" my way to what I hope is a high-fidelity HTML to docx converter.
A few things about where it landed:
- Native OOXML output, real Word structure, not a screenshot or a 1x1 table pretending to be a document - Works in Node, in the browser (no Playwright needed for the default path), and as a CLI (npx dom-docx input.html -o output.docx) - MIT licensed - Full benchmark methodology + results vs the established OSS alternatives: https://github.com/floodtide/dom-docx/blob/main/docs/BENCHMA...
Live demo if you want to test HTML conversion in the browser: https://dom-docx.com
Happy to answer anything about the scoring loop or anything else.
PS: This is the first thing I've open sourced and I'm excited to see where it leads!
That's an interesting approach. I'm concerned about the use of LibreOffice as your source of truth. Would it be possible to swap out LibreOffice for actual MS Word in this workflow? This also could reveal some libreoffice rendering bugs/edge cases that are worth filing bugs over.
I don’t have MS word installed on my development machine, so I haven’t done much testing with Word, but that does sound like a good idea to run the suite using Word. For what it’s worth I did not notice any issues with LibreOffice, even after running many iterations and tests.
I would add a +1 for testing w/ Word - the official Office suite runs some validation where only Word will show a "broken file" popup, even when nothing else does.
In our case, clients use only real Word, so any machine-generated/mutated files (excel/ppt as well) need a pass through the real office executable.
Thanks for the feedback, I’ll add Word validation to my todo list.
In my experience a docx that looks good in libreoffice usually looks good in word, it's the other way around that is usually more of a problem.
I spent two days last week trying to figure out why a docx file I was generating with python-docx looked fine in libreoffice but would not open in word. it was just some text with a circle overlaid on it, but word is a lot fussier about the xml structure of the document than libreoffice is. finally had to create the same structure directly in msword and have claude examine the two files for differences.
Sounds to good to be true, but it works for the given examples! What is the scope though? It produces garbage with larger documents with tables and figures. For example this large document, even with removed menu and headings: https://docs.redhat.com/en/documentation/red_hat_enterprise_...
Could it be it has only been fed small documents?
All of the suite test cases are small fragments of HTML to test specific things, so I probably do need a way to test bigger documents. Thanks for the feedback. I’ll add that to the to-do list.
I’ll try the red hat example later this evening.
Ok, I dug into the Red Hat doc. It’s a great example and it uncovered a few real shortcomings.
A couple of things about this scenario:
First, the page relies on stylesheets, so you need styleSource: "computed", either Playwright on Node, or run in the browser with the content already rendered.
Second, dom-docx doesn’t fetch remote images itself. The caller supplies an imageResolver (e.g. a fetch callback), which keeps security, timeouts, host allowlists, etc. under caller control: https://dom-docx.com/learn#image-resolver
I fixed a few bugs from this (in 0.1.8):
- wide headings inside flex containers getting clipped
- oversized images not scaling down to the printable page width
- OS dark theme (prefers-color-scheme: dark) leaking near-white computed text colors into Word on the browser path
I also added an ad-hoc repo script that loads a live URL, takes a CSS selector, and converts with Playwright (tools/try-url.ts). I used it on the RHEL page and got a pretty decent 200+ page doc. Some tables still look wrong — I’ll dig into those next.
Script: https://github.com/floodtide/dom-docx/blob/main/tools/try-ur...
Example usage from a clone: npx tsx tools/try-url.ts \ "https://docs.redhat.com/en/documentation/red_hat_enterprise_..." \ ".docs-content-container" \ rhel-storage.docx
Thanks for following up. I don't understand why your post has been flagged.
Interesting but how is an "autoresearch loop" different than creating a spec and X number of testcases and letting an agent run against these testcases and the spec?
Scoring would probably be the big difference because the outcome is to optimize performance or optimize a score or a metric versus just a pass fail.
This is very cool and thanks for sharing the workflow, buuuuuut... Could you please rewrite the README in your own words? If not for this comment, I would have just flagged this submission without looking into it further, because no matter how useful the premise is, it feels like one of the millions “I’ve burnt a bunch of tokens and thrown the result on GitHub” kinda projects you see nowadays. Clearly that’s not the case here, but an LLM-generated README really does your project a disservice.
I hear you, thanks for the feedback. I've done that some already but of course it could be better in more of my own voice.
Very interesting approach. I am having trouble with page breaks (documentation says they work, but demo pages dont) etc. For the invoicing example this would require table breaks/overflows into subsequent pages in a real application and I am currently evaluating going with model->PDF or model->DOCX
Do you have any approach in this regard that works ?
I tested this, but it seems like it regressed somehow. It may not be working in the browser side use case right now. I'll have to look at it later this evening. I created a GH issue to keep it on the radar: https://github.com/floodtide/dom-docx/issues/5
Could you update the GH issue with a bit more information about your specific use case?
Just adding, since I don't see it mentioned in the readme, that its written in Typescript. That's what makes this interesting. I imagine Pandoc can do this but its not Typescript (its Haskell).
pandoc purportedly can run as wasm: https://github.com/haskell-wasm/pandoc-wasm
The screenshot-to-docx scoring loop is a clever way to verify layout fidelity. Very useful for anyone generating reports from HTML.
Thanks, and just to mention, I’ve had awesome results using Autoresearch loops on other things like SQL performance.
Prompt example:
You are a SQL performance researcher. Run the following SQL query to establish a baseline, then come up with hypotheses to improve performance. Score each result and run 5 iterations. Avoid any regressions, each result must contain the exact same rows and columns.
See https://github.com/karpathy/autoresearch
Also works wonderful for generating AI scripts, goal being increasing the elo rating after a tournament run. Also having deep and shallow tests save a lot of time. Deep tests are run sparingly while shallow tests are run after each change.
Awesome, thanks so much for open-sourcing! Will use it to generate my C.V. in Word format.
I have done something similar for PPTX, keeping the fidility intact was really challenging with computed values & OOXML counterparts and again challanges with different XML implementations like that of MS & Libre..
Agreed, visual fidelity is pretty hard, and that’s why none of the scores are 100.
Surely I can't be the only one who misread the heading and clicked expecting to see DOOM implemented using just HTML DOM. :-/
For that you probably want this, lol: https://cssdoom.wtf/
Pretty sure that has been done. I clicked to see DOOM implemented using OOXML.
I'd be thrilled if this could lead to higher fidelity print and Save-to-PDF functionality in browsers.
Broken printing is a failure/intention of website developers. It’s very easy to define print styles with a `@media print {…}` CSS query. Few sites use it.
this is cool. I'm curious how many tokens ($) it cost you to build?
i'm also building in this space (an MCP for agents to manipulate docx)
I did everything with the Cursor $20 plan and the Claude Code $20 plan, so in this particular case it wasn’t actually that many tokens. This was over the course of about four weeks of weekend and evening work.
Can this go docx -> html -> docx?
Not yet, but I’ve actually thought about that and want to investigate that possibility at some point!
Good work on the effort to the author.
And every time y'all, how absurd is it that this still has to exist? It never stops being wild to me.
I don’t completely follow. Why is it absurd to want to generate documents that are editable by humans?
No, I mean it's absurd that a horrible "standard" like a Word Doc has such staying power, and that we have to keep writing things against it.
Since HTML is so rich and the DX is amazing these days, I wish HTML file sharing for the document use case (and using the browser as a client) was widely accepted, it’s another problem/opportunity I’ve pondered a lot.
it could be worse and be completely closed source like google docs