9.11.0

Highlights

HTML to docx: docx/html

You can now turn HTML into document content. This is one of the most requested features (#2632, and many issues before it). It's an optional entry, docx/html, so docx itself doesn't grow.

import { Document } from "docx";
import { htmlToContent } from "docx/html";

const doc = new Document({
    sections: [{ children: htmlToContent("<h1>Report</h1><p>Sales were <b>up 12%</b>.</p><ul><li>EMEA</li></ul>") }],
});

• htmlToContent returns paragraphs and tables. Use it in sections, headers, footers, table cells, text boxes and PatchType.DOCUMENT patches.
• htmlToRuns returns a paragraph's content. Use it in paragraphs and PatchType.PARAGRAPH patches.
• Other converters write a whole document. This output mixes with everything else docx makes.
• HTML is parsed as browsers parse it, with a CSS cascade and selectors.
• It reads text formatting, lists, tables, images, links, bookmarks, footnotes, MathML and LaTeX, checkboxes, tracked changes and page breaks.
• The HTML of editors such as CKEditor, Quill, TipTap, Lexical, Google Docs and Word comes out as it looked in the editor.
• Output uses the document's own styles (Normal, Heading 1–6, List Paragraph, Hyperlink). styleMap maps CSS selectors to your styles.
• What can't be converted is reported to onWarning. The HTML never causes an error, and nothing in it is run or fetched.

See the HTML documentation. In a page without a bundler, load dist/html.umd.cjs after dist/index.umd.cjs and dist/math.umd.cjs.

Two additions to docx came with it. They are useful on their own:

• Lists that bring their own definitions. A paragraph's numbering.reference can be a definition, { reference, levels }. It is added to the document's numbering when the paragraph is written.
• Notes that bring their own content. FootnoteReferenceRun and EndnoteReferenceRun can be given their note's content, { children }, instead of an id. The note is added to the document with an id of its own.

patchDocument fixes

• Lists (#3750): patchDocument takes a numbering option, the same as a Document's. Numbered and bulleted paragraphs in patches now work. Before, they threw a TypeError, wrote ids Word couldn't open, or came out as plain text. The templates docs also show how to add an optional item to a list in the template. Closes #2088, #2966, #3194 and #3399.
• Headings and styles (#3751): headings in a patch kept Heading1 and the other heading ids, but Word-made templates often don't have those styles, so the headings showed as body text. The styles patches use are now added when the template doesn't have them. When a template from Word in another language has a style with the same name under another id, that style is used. Closes #2735.
• Images (#3749): each drawing a patch inserts gets an id no other drawing in the file has. Before, a patched image could share an id with a drawing in the template, which makes Word report unreadable content. Closes #2719.

Other fixes

• specVanish is written from its own option instead of from vanish (#3746). Thanks @builtbysharath!

What's Changed

• docs: fix mistakes found while answering discussions by @dolanmiu in #3748
• fix: patchDocument gives each drawing it inserts an id no other drawing has by @dolanmiu in #3749
• fix: numbered and bulleted paragraphs in patchDocument by @dolanmiu in #3750
• fix: headings in patchDocument keep their style in templates without it by @dolanmiu in #3751
• fix: write specVanish from its own option instead of vanish by @builtbysharath in #3746
• test: read the year 10000 boundary in UTC in every time zone by @builtbysharath in #3747
• feat: docx/html, HTML as a document's content (#2632) by @dolanmiu in #3752
• build(deps-dev): bump execa from 10.0.1 to 10.1.0 by @dependabot[bot] in #3753
• build(deps): bump @types/node from 26.6.4 to 26.6.5 by @dependabot[bot] in #3755
• build(deps-dev): bump eslint-plugin-jsdoc from 65.1.0 to 65.2.4 by @dependabot[bot] in #3757
• build(deps-dev): bump prettier from 3.9.9 to 3.9.10 by @dependabot[bot] in #3756
• build(deps-dev): bump vite from 8.3.3 to 8.3.4 by @dependabot[bot] in #3754
• chore: Version bump to 9.11.0 by @dolanmiu in #3758

New Contributors

• @builtbysharath made their first contribution in #3746

Full Changelog: 9.10.0...9.11.0