Show HN: DOM-docx – HTMLからネイティブで編集可能なWordドキュメントへ (MIT)
Show HN: DOM-docx – HTML to native, editable Word docs (MIT) (github.com)
要約
DOM-docxは、HTMLフラグメントをネイティブで編集可能なWordドキュメント(OOXML)に変換するライブラリです。段落、テーブル、画像などをサポートし、スクリーンショットやレイアウトハックではなく、構造的な忠実性を重視しています。Node.js環境またはブラウザ内で動作し、インラインスタイルや計算されたスタイル、さらにはCanvasやSVGのラスタライズにも対応しています。
全文翻訳
dom-docx
セマンティックなHTMLをネイティブで編集可能なdocxファイル(OOXML)に変換します。段落、ラン、リスト、テーブル、フレックス、画像がすべてサポートされています。
ライブデモ: dom-docx.com。コンバーターを試したり、ショーケースを閲覧したり、学習ガイドを読んだりできます。
ビジュアルリグレッションループで構築されています。ChromiumでHTMLをレンダリングし、docxに変換し、LibreOfficeでラスタライズし、人間が検証したメトリックに対してレイアウトと構造の忠実度をスコアリングし、イテレーションします。最新スコア: TEST-SCORES.md · 方法論: SCORING.md。
インストール
npm install dom-docx
Node.js ≥ 20 が必要です。デフォルトの inline パスにはブラウザやPlaywrightは不要です。
Playwrightが必要な場合
| エントリ | styleSource: "inline" | styleSource: "computed" | rasterizeInPlace |
|---|---|---|---|
Node (dom-docx) | 純粋なJS、ブラウザ不要 | Playwright + Chromium | Playwright + Chromium (同じヘッドレスページ) |
ブラウザ (dom-docx/browser) | 純粋なJS、ライブDOM不要 | ライブページ: ネイティブ getComputedStyle | ライブページ: canvas/SVG → PNG <img> をタブ内に表示 |
Nodeでは、playwright はオプションのピア依存関係です。npm install dom-docx は docx、cheerio、fflate のみをプルします。styleSource: "computed" または rasterizeInPlace を渡したときに遅延ロードされます。これらのパスを使用するには、PlaywrightとChromiumを自分で一度インストールしてください。
npm install playwright
npx playwright install chromium
Playwrightは開発テストハーネス(ライブラリの使用には不要)でも使用されます。コントリビューター: クローン後 npm run setup。
LibreOfficeは変換に必要ありません。ビジュアルテストハーネスにのみ使用されます。
クイックスタート
Node
import { writeFile } from "node:fs/promises";
import { convertHtmlToDocx } from "dom-docx";
const html = `
<h1 style="color:#1a1a2e">Quarterly Report</h1>
<p>Revenue grew <strong>12%</strong> year over year.</p>
<ul>
<li>North America</li>
<li>EMEA</li>
</ul>
`;
const docx = await convertHtmlToDocx(html);
await writeFile("output.docx", docx);
bodyフラグメントのみ(<!DOCTYPE> / <html> / <body> は不要)を渡します。デフォルト: USレター、1インチのマージン、Arial 10.5ptの本文テキスト。
ブラウザ
import { convertHtmlToDocx } from "dom-docx/browser";
const html = `
<h1 style="color:#1a1a2e">Quarterly Report</h1>
<p>Revenue grew <strong>12%</strong> year over year.</p>
<ul>
<li>North America</li>
<li>EMEA</li>
</ul>
`;
const blob = await convertHtmlToDocx(html);
// 例: ブラウザでダウンロードをトリガー
const a = document.createElement("a");
a.href = URL.createObjectURL(blob);
a.download = "output.docx";
a.click();
PlaywrightもNodeも不要です。これはユーザーのタブ内で完全に実行されます。Browser bundleを参照してください。
CLI
コードを書かずにファイルを変換できます。
npx dom-docx input.html -o output.docx
npx dom-docx input.html # 隣にinput.docxを書き込む
cat fragment.html | npx dom-docx - -o - # 標準入力 → バイナリ標準出力 (パイプライン)
npx dom-docx input.html -s computed # スタイルシート/クラスHTML (playwrightのインストールが必要)
npm install -g dom-docx # オプション: グローバルにインストールし、"dom-docx" を npx なしで実行
入力はAPIと同じbody HTMLフラグメントです。すべてのオプションについては --help を参照してください。
v1.x の機能
サポートされている(デフォルト styleSource: "inline"):
- 見出し、段落、リスト(
<ul>/<ol>、list-style-typeを含む)、テーブル、リンク、インラインフォーマット - ブロック背景、引用ブロック、
<hr>、シンプルなフレックス行(≤4項目) data:画像;imageResolverを介したリモート画像- ページサイズ/向き/マージン、デフォルトフォント、メタデータ、ヘッダー/フッターHTML、ページ番号、目次、言語/方向
- 低複雑度のインラインSVG(バー + テキスト)
- テーブルセル内のCSSバーdiv(背景 + 高さ/幅 → ネイティブシェーディングバンド)
高度(オプション styleSource: "computed"):
getComputedStyleを介して<style>ブロックおよびクラス/#idセレクターを解決します。- Node:
playwright(オプションのピア依存関係、別途インストール)+ Chromiumが必要です。ライブラリはヘッドレスChromiumを起動してフラグメントをレンダリングします。 - ブラウザバンドル: ユーザーのタブのライブDOMを使用します。Playwrightや追加のインストールは不要です。
- SPAフラグメントエクスポート:
element.innerHTMLを変換する際にroot(ブラウザ)またはrootSelector(Node + ライブpage)を渡して、計算されたスタイルパスがフラグメントツリーと一致するようにします。 - インラインは npmインストール時のサポートされているデフォルトです。計算済みは、スタイルシート/クラス用、または既にレンダリングされたページがある場合に使用します。
チャートと複雑なSVG(オプション rasterizeInPlace):
- 変換前に
<canvas>および複雑な<svg>(例: Highcharts)をPNG<img>にラスタライズします。 - チャートに推奨:
rasterizeInPlace: { scale: 2 }— Wordでより鮮明な画像を得るために2倍の密度でスーパーサンプリングします(デフォルトscale: 1、最大4)。 - Node: 計算済みスタイルと同じPlaywright/Chromiumコンテキストを使用します。エフェメラルなスパンページはデフォルトでインプレースで変更されます。
- ブラウザ:
rootが必要です。ライブページが変更されないように、デフォルトでオフスクリーンにクローンします。 - 単純なインラインSVG(rect + textバーチャート)は、ラスタライズなしでネイティブに変換されます。
v1.x ではサポートされていません:
- インラインパスでの外部スタイルシート(計算済みまたはすべてのインラインスタイルを使用してください)。
- Webフォント、CSSグリッド/フロートレイアウト、フォーム、
<pre>の整形、<dl>、テーブルのrowspan。 - ヘッダー/フッターの最初のページ/偶数ページバリアント。保証された複数ページレイアウトの忠実度。
- 複雑なSVG(パス、グラデーション、
<use>)(rasterizeInPlaceをライブレンダリングページで使用しない場合)。
HTMLオーサリングティアについては AGENTS.md を、完全なオプションについては API.md を参照してください。
API
convertHtmlToDocx(html, options?)
有効な .docx ファイルを含む Promise<Buffer>(Node)を返します。
import { convertHtmlToDocx, type ConvertOptions } from "dom-docx";
const docx = await convertHtmlToDocx(html, {
pageSize: "a4",
orientation: "landscape",
margins: { top: 0.75, bottom: 0.75 }, // インチ; 省略されたサイドはデフォルトで1インチ
defaultFont: { family: "Georgia", sizePt: 11 },
metadata: { title: "Q3 Report", creator: "Finance" },
headerHtml: "<p style='font-size:12px;color:#666'>Confidential</p>",
footerHtml: "<p style='font-size:12px'>© 2026 ACME</p>",
pageNumber: true,
lang: "en-US",
direction: "ltr",
coverHtml: "<h1 style='text-align:center'>Quarterly Review</h1>", // ページ1、TOCの前
tocHtml: "<ol><li><a href='#intro'>Introduction</a></li></ol>", // あなたのTOC; リンクはid="intro"にジャンプします
});
オプション
| オプション | デフォルト | 説明 |
|---|---|---|
styleSource | "inline" | "inline" は style="" のみ解析します(純粋JS、高速)。"computed" は getComputedStyle を使用します。Node ではPlaywright + Chromiumが必要。ブラウザバンドルではライブDOMから読み取ります(Playwright不要)。 |
browser / page | — | Nodeのみ。 開いているPlaywrightブラウザまたはページを再利用します(計算済みスタイルおよび/または rasterizeInPlace)。dom-docx/browser では使用しません。 |
rootSelector | — | Nodeのみ。 ライブPlaywright page から element.innerHTML を変換する際の、エクスポートルートのCSSセレクター。渡すHTMLのノードと一致する必要があります。 |
rasterizeInPlace | — | 変換前に <canvas> / チャート <svg> をPNG <img> にラスタライズします。推奨: チャートエクスポートには { scale: 2 }。Node: Playwrightページ。ブラウザ: root が必要です。API.md を参照してください。 |
imageResolver | — | data: URL以外の <img src> を取得するためのフック(ライブラリは自分で取得しません)。 |
onWarning | console.warn | 出力がサイレントに劣化した場合(画像が見つからない、styleSource: "inline" でクラス/スタイルシートCSSが無視された場合)に呼び出されます。抑制するには null を渡します。 |
pageSize | "letter" | ` |