🚀 Building KritiDocX: The Industrial-Grade HTML & Markdown to Word Compiler (Built with Google AI)

Hoffawhy — Thu, 19 Mar 2026 05:43:52 +0000

If you’ve ever tried automating Microsoft Word (.docx) reports using Python, you know the struggle.

Generating a simple paragraph? Easy.

Generating a complex HTML table with rowspan, colspan, CSS padding, and floating graphics? Absolute nightmare. Existing libraries either crash, corrupt the XML, or simply paste unformatted text onto a blank canvas.

I faced this exact problem. I wanted a way to separate my Design (HTML/CSS) from my Data (Markdown/LaTeX) and compile them together perfectly into MS Word.

Since I couldn't find a tool that did this properly—I built one. And the craziest part? Coming from a non-coding background, I architected the entire engine collaborating exclusively with Google AI Studio in just 30 days! 🤯

Meet KritiDocX.

🔥 What Makes KritiDocX Different?

Most HTML-to-Word converters are simple parsers. KritiDocX is an actual Compiler. It reads the DOM, calculates physics, and rebuilds the geometry natively in OOXML.

Here is what it brings to the table:

1. The 2D Matrix Engine (Flawless Tables) ▦

CSS web tables are fluid; MS Word tables are strict geometric grids. When you feed KritiDocX a table with overlapping <th rowspan="3">, it doesn’t just guess. It plots a 2D mathematical matrix in memory before rendering. Result? Pixel-perfect merged cells with zero CSS border collisions!

2. Scientific & Mathematical Core (OMML) 🧮

No more blurry PNG images for your equations.
Pass pure LaTeX ($$ E = mc^2 $$) in your Markdown or HTML. KritiDocX’s internal engine converts it into Native MS Word Editable Equations using XSLT transformations. It even expands matrices dynamically (\begin{bmatrix}) so brackets wrap correctly around fractions!

3. Native Word Interactive Forms (SDT) ☑️

HTML <input type="checkbox" checked> won’t just output a static [X]. The engine translates web forms into MS Word Structured Document Tags. You get actual, clickable Word Checkboxes, Dropdown lists, and Text fields with placeholder text right inside the .docx!

4. The "Hybrid" Injection Mode 🧬

This is the killer feature for automated reporting. You keep your beautiful corporate letterheads and styles in an HTML template, and feed your dynamic database payload via a .md file. KritiDocX merges them flawlessly, allowing the markdown data to inherit all the CSS styles from the HTML wrapper!

⚡ The API: A True "Zero-Friction" Facade

Despite the crazy complexity of XML handling, XSLT translations, and AST DOM routing under the hood, the Public API is literally just one single function call.

You don’t have to manually manage Word buffers, loops, or styles. The engine auto-detects .md and .html formats dynamically!

Mode 1: Simple HTML/Markdown Conversion

from kritidocx import convert_document

# Takes care of CSS Borders, Backgrounds, Margins, and Native Forms automatically.
convert_document(
    input_file="fancy_layout.html", 
    output_file="Corporate_Report.docx"
)

# Works natively with Math and Code Blocks too!
convert_document("research_paper.md", "Physics_Output.docx")

Mode 2: Hybrid Injection (Data + Template)

This allows massive scale reporting pipelines:

from kritidocx import convert_document

convert_document(
    input_file="company_header_footer_design.html",  # Your Design Layer
    data_source="quarterly_data.md",                 # Your Data Payload
    output_file="Auto_Generated_Report.docx"
)

(Under the hood, the engine scans the HTML for a <main> or <div id="content"> and intelligently injects the parsed Markdown flow inside it, applying inherited CSS typography constraints).

🛠️ The Architecture (For the Tech Geeks)

Building this required bypassing many limitations of standard python-docx wrappers by digging straight into lxml tree parsing.

Handling CSS 'Float' and 'Absolute': The CSS engine captures Z-indexes, left/top margins, and absolute commands. The XML factory translates these into <wp:anchor> DrawingML properties so shapes can actually float OVER your Word text (great for "CONFIDENTIAL DRAFT" watermarks!).
Multi-Script Fonts: Prevents the infamous "tofu" boxes [][] when printing Hindi, Asian characters, or Checkbox symbols. The font handler routes English to Calibri (ascii) and Complex scripts to fonts like Mangal natively (cs).
Resilient Cloud Caching: Need a remote <img src="http..."/>? The built-in loader automatically safely fetches, validates metadata, and caches network images without exploding Serverless memory on services like AWS Lambda/Vercel (Thanks to integrated LRU limiters!).

🚀 Give It a Try!

If you generate automated reports, invoices, analytical summaries, or scientific papers, KritiDocX will save your development team weeks of template-building headaches.

📦 Install via Pip: pip install kritidocx
🧪 Test the Engine Live (Zero Code): Check out the live Browser Playground
📖 Deep-Dive the Documentation: Head to hoffawhy.github.io/KritiDocX

If you like what you see, please consider giving the repository a ⭐ on GitHub. It really helps Open Source projects get noticed!
Explore the Code on GitHub

I would love to hear what the community thinks! What edge cases of HTML to DOCX conversions have you struggled with the most? Drop your thoughts in the comments! 👇

DEV Community: Hoffawhy