docx-templates-html v1.0.3

docx-templates-html

A TypeScript library for converting HTML tags to DOCX literal XML. This library helps you transform HTML content into DOCX-compatible XML markup that can be used in DOCX templates (https://github.com/guigrpa/docx-templates).

Installation

via npm

npm install install docx-templates-html

or yarn

yarn add install docx-templates-html

Usage for basic conversion

import { convertHtmlToDocx } from 'docx-templates-html';

// Basic conversion
const html = '<p>Hello <strong>World</strong>!</p>';
const docxXml = convertHtmlToDocx(html);
console.log(docxXml);
// Output: <w:p><w:r><w:rPr/><w:t xml:space="preserve">Hello </w:t></w:r><w:r><w:rPr><w:b/></w:rPr><w:t xml:space="preserve">World</w:t></w:r><w:r><w:rPr/><w:t xml:space="preserve">!</w:t></w:r></w:p>

Usage for full docx encapsulation (needed to add separator || before and after text)

import { convertHtmlToDocx, addDocxEncapsulation } from 'docx-templates-html';

// Basic conversion
const html = '<p>Hello <strong>World</strong>!</p>';
const docxXml = convertHtmlToDocx(html);
console.log(docxXml);
// Output: <w:p><w:r><w:rPr/><w:t xml:space="preserve">Hello </w:t></w:r><w:r><w:rPr><w:b/></w:rPr><w:t xml:space="preserve">World</w:t></w:r><w:r><w:rPr/><w:t xml:space="preserve">!</w:t></w:r></w:p>

// With template encapsulation
const encapsulatedXml = addDocxEncapsulation(docxXml);
// Output: ||</w:t></w:r></w:p><w:p><w:r><w:rPr/><w:t xml:space="preserve">Hello </w:t></w:r><w:r><w:rPr><w:b/></w:rPr><w:t xml:space="preserve">World</w:t></w:r><w:r><w:rPr/><w:t xml:space="preserve">!</w:t></w:r></w:p><w:p><w:r><w:t>||

Examples

Text Formatting

// Bold text
convertHtmlToDocx('<p><strong>Important</strong></p>');
// <w:p><w:r><w:rPr><w:b/></w:rPr><w:t xml:space="preserve">Important</w:t></w:r></w:p>

// Italic text
convertHtmlToDocx('<p><em>Emphasized</em></p>');
// <w:p><w:r><w:rPr><w:i/></w:rPr><w:t xml:space="preserve">Emphasized</w:t></w:r></w:p>

// Underlined text
convertHtmlToDocx('<p><u>Underlined</u></p>');
// <w:p><w:r><w:rPr><w:u w:val="single"/></w:rPr><w:t xml:space="preserve">Underlined</w:t></w:r></w:p>

// Strikethrough text
convertHtmlToDocx('<p><s>Outdated</s></p>');
// <w:p><w:r><w:rPr><w:strike w:val="true"/></w:rPr><w:t xml:space="preserve">Outdated</w:t></w:r></w:p>

Superscript and Subscript

// Superscript
convertHtmlToDocx('<p>x<sup>2</sup></p>');
// <w:p><w:r><w:rPr/><w:t xml:space="preserve">x</w:t></w:r><w:r><w:rPr><w:vertAlign w:val="superscript"/></w:rPr><w:t xml:space="preserve">2</w:t></w:r></w:p>

// Subscript
convertHtmlToDocx('<p>H<sub>2</sub>O</p>');
// <w:p><w:r><w:rPr/><w:t xml:space="preserve">H</w:t></w:r><w:r><w:rPr><w:vertAlign w:val="subscript"/></w:rPr><w:t xml:space="preserve">2</w:t></w:r><w:r><w:rPr/><w:t xml:space="preserve">O</w:t></w:r></w:p>

Lists

// Unordered list
convertHtmlToDocx('<ul><li>Apple</li><li>Banana</li></ul>');
/* Output:
<w:p><w:pPr><w:pStyle w:val="Normal"/><w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr></w:pPr><w:r><w:rPr/><w:t xml:space="preserve">Apple</w:t></w:r></w:p>
<w:p><w:pPr><w:pStyle w:val="Normal"/><w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr></w:pPr><w:r><w:rPr/><w:t xml:space="preserve">Banana</w:t></w:r></w:p>
*/

// Ordered list
convertHtmlToDocx('<ol><li>First</li><li>Second</li></ol>');
/* Output:
<w:p><w:pPr><w:pStyle w:val="Normal"/><w:numPr><w:ilvl w:val="0"/><w:numId w:val="2"/></w:numPr></w:pPr><w:r><w:rPr/><w:t xml:space="preserve">First</w:t></w:r></w:p>
<w:p><w:pPr><w:pStyle w:val="Normal"/><w:numPr><w:ilvl w:val="0"/><w:numId w:val="2"/></w:numPr></w:pPr><w:r><w:rPr/><w:t xml:space="preserve">Second</w:t></w:r></w:p>
*/

Mixed Formatting

// Nested formatting
convertHtmlToDocx('<p><em><strong>Important italic text</strong> just italic text</em></p>');
/* Output:
<w:p><w:r><w:rPr><w:i/><w:b/></w:rPr><w:t xml:space="preserve">Important italic text</w:t></w:r><w:r><w:rPr><w:i/></w:rPr><w:t xml:space="preserve"> just italic text</w:t></w:r></w:p>
*/

Supported HTML Tags

• Block Elements:

  • <p> - Paragraphs
  • <ul> - Unordered lists
  • <ol> - Ordered lists
  • <li> - List items

• Text Formatting:

  • <strong>, <b> - Bold text
  • <em>, <i> - Italic text
  • <u> - Underlined text
  • <s> - Strikethrough text
  • <sup> - Superscript
  • <sub> - Subscript

• Line Breaks:

  • <br> - Line break

Features

• Clean and focused TypeScript implementation
• Strong typing with comprehensive type definitions
• Efficient HTML cleaning and parsing
• Tag normalization (<b> → <strong>, <i> → <em>)
• Configurable tag mapping
• Comprehensive test coverage
• Optional DOCX encapsulation for template usage

License

MIT