DocGen

Converts HTML into DOCX, PPTX and vice versa. Runs in browsers (via bundled JS) and Node.js (via CLI). Published as docgen-utils on npm.

Key Components

Build & Distribution

| File | Description | | ---------- | -------------------------------------------------------------- | | build.sh | Builds the library (TypeScript → esbuild bundles) | | dist/ | Output directory containing production-ready minified JS files |

Package Structure

| Package | Description | | ------------------ | --------------------------------------------------------------------------------- | | packages/docs/ | DOCX pipeline — 13 TypeScript files for HTML↔DOCX conversion | | packages/slides/ | PPTX pipeline — 8 TypeScript files + vendored PptxGenJS for HTML↔PPTX conversion | | packages/shared/ | Cross-cutting utilities — DOM parser shim, proxy-aware HTTP client, font mappings | | packages/cli/ | Node.js CLI (docgen command) — dispatches to import/export subcommands |

Usage

Install dependencies

npm install --registry=https://registry.npmjs.org

Build

npm run build

CLI

The CLI is used in the agent sandbox to transform artifacts.

alias docgen='npx tsx packages/cli'
docgen import docx --file=file.docx --out-dir=./output [--name=<filename>]
docgen import pptx --file=file.pptx --out-dir=./output [--name=<filename>]
docgen export docs --file=file.html --out-dir=./output [--name=<filename>] [--pageless] [--pdf]
docgen export slides --files=slide-1.html,slide-2.html --out-dir=./output [--name=<filename>] [--pdf]

Visual Comparison

The output directory contains the rendered output in target formats. e.g. DOCX or PPTX vs HTML

• Files in test-data/docs/ (28 HTML files) → converted to DOCX → docx-render.jpg
• Files in test-data/slides/ (90 HTML files) → converted to PPTX → pptx-render.jpg
• Files in test-data/pptx/ (145 PPTX files) → imported to HTML → html-render.jpg
• Files in test-data/docx/ (22 DOCX files) → imported to HTML → html-render.jpg

Prerequisites

Install the required system dependencies:

macOS:

# LibreOffice (for DOCX/PPTX → PDF conversion)
brew install --cask libreoffice
# Poppler (for PDF → PNG conversion)
brew install poppler
# Chromium for Playwright
npx playwright install chromium
# Install fonts for accurate rendering
npx tsx scripts/install-fonts/index.ts

Usage

Process a specific document (HTML -> DOCX):

npm run generate-output -- test-data/docs/doc-1.html

Process a specific slide (HTML -> PPTX):

npm run generate-output -- test-data/slides/slide-1.html

Import a PPTX file (PPTX -> HTML):

npm run generate-output -- test-data/pptx/presentation.pptx

Import a DOCX file (DOCX -> HTML):

npm run generate-output -- test-data/docx/document.docx

Process multiple files:

npm run generate-all-docs-output   # All docs (HTML→DOCX)
npm run generate-all-slides-output # All slides (HTML→PPTX)
npm run generate-all-docx-output   # All DOCX imports (DOCX→HTML)
npm run generate-all-pptx-output   # All PPTX imports (PPTX→HTML)

Roundtrip Testing

Full roundtrip tests convert HTML→DOCX/PPTX→HTML and compare the result:

npm run roundtrip -- test-data/docs/doc-1.html       # Single doc roundtrip
npm run roundtrip -- test-data/slides/slide-1.html    # Single slide roundtrip
npm run roundtrip-all-docs                             # All docs (no AI diff)
npm run roundtrip-all-slides                           # All slides (no AI diff)

AI-Powered Visual Diff

Compare two rendered images using Claude vision API (requires ANTHROPIC_API_KEY):

npm run ai-diff <image1.jpg> <image2.jpg>
npm run ai-diff -- <image1.jpg> <image2.jpg> --question="Is the text shadow rendering correctly?"

Output

The script generates the following structure:

output/
├── doc-1.html/
│   ├── html-render.jpg       # Screenshot of HTML (via Playwright)
│   ├── docx-render.jpg       # DOCX rendered via LibreOffice
│   ├── diff.jpg              # Visual diff highlighting differences
│   ├── output.docx           # Generated DOCX file
│   └── report.json           # Comparison metrics
├── slide-1.html/
│   ├── html-render.jpg       # Screenshot of HTML (via Playwright)
│   ├── pptx-render.jpg       # PPTX rendered via LibreOffice
│   ├── diff.jpg              # Visual diff highlighting differences
│   ├── output.pptx           # Generated PPTX file
│   └── report.json           # Comparison metrics
├── presentation.pptx/
│   ├── pptx-render.jpg       # Original PPTX rendered via LibreOffice
│   ├── html-render.jpg       # Imported HTML rendered via Playwright
│   ├── diff.jpg              # Visual diff highlighting differences
│   ├── output.html           # Generated HTML (all slides concatenated)
│   └── report.json           # Comparison metrics
├── metrics.json              # Aggregated quality metrics across all tests
└── ...

Quality Metrics

A pre-commit hook automatically aggregates all report.json files into output/metrics.json, tracking quality baselines by conversion type (docx-export, pptx-export, docx-import, pptx-import).

Metrics explained:

• pixelDiff.percentDiff - Percentage of pixels that differ between the two images (lower is better)
• ssim.mssim - Structural Similarity Index (0-1, higher is better). Values above 0.9 indicate very similar images
• Quality Score - Composite score 0-100 for roundtrip tests (target ≥85)