+
+
+```
+
+## What it shows
+
+[](https://github.com/TurboDocx/html-to-docx/blob/develop/.github/workflows/docx-diff.yml)
+
+This badge demonstrates that your project uses **TurboDocx's automated DOCX regression testing** to ensure consistent, high-quality HTML to DOCX conversion.
+
+## SEO Keywords
+
+- HTML to DOCX conversion
+- DOCX regression testing
+- Automated document generation testing
+- TurboDocx
+- html-to-docx library
+- DOCX diff analysis
+- Document generation CI/CD
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..9205a0b
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,32 @@
+version: 2
+
+updates:
+ # NPM dependencies - security updates only
+ - package-ecosystem: "npm"
+ directory: "/"
+ schedule:
+ interval: "daily"
+ target-branch: "develop"
+ commit-message:
+ prefix: "security"
+ include: "scope"
+ # Disable version updates for npm dependencies
+ open-pull-requests-limit: 0
+ allow:
+ - dependency-type: "all"
+ rebase-strategy: "auto"
+
+ # GitHub Actions dependencies - security updates only
+ - package-ecosystem: "github-actions"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ target-branch: "develop"
+ commit-message:
+ prefix: "security"
+ include: "scope"
+ # Disable version updates for GitHub Actions dependencies
+ open-pull-requests-limit: 0
+ allow:
+ - dependency-type: "all"
+ rebase-strategy: "auto"
diff --git a/.github/scripts/update-contributors.js b/.github/scripts/update-contributors.js
new file mode 100755
index 0000000..c9fec47
--- /dev/null
+++ b/.github/scripts/update-contributors.js
@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Configuration
+const PACKAGE_JSON_PATH = path.join(process.cwd(), 'package.json');
+const EXCLUDED_USERS = ['dependabot[bot]', 'dependabot', 'github-actions[bot]'];
+
+async function getGitHubUserEmail(username) {
+ try {
+ const response = await fetch(`https://api.github.com/users/${username}`, {
+ headers: {
+ 'Authorization': `token ${process.env.GITHUB_TOKEN}`,
+ 'User-Agent': 'contributor-bot'
+ }
+ });
+
+ if (response.ok) {
+ const user = await response.json();
+ return user.email;
+ }
+ } catch (error) {
+ console.log(`Could not fetch email for ${username}:`, error.message);
+ }
+ return null;
+}
+
+function formatContributor(username, email) {
+ if (email && email !== 'null' && email !== '') {
+ return `${username} <${email}>`;
+ }
+ return username;
+}
+
+function isContributorAlreadyListed(contributors, username) {
+ const normalizedUsername = username.toLowerCase();
+ return contributors.some(contributor => {
+ const contributorName = contributor.split(' ')[0].toLowerCase();
+ return contributorName === normalizedUsername;
+ });
+}
+
+async function updateContributors() {
+ const prAuthor = process.env.PR_AUTHOR;
+
+ if (!prAuthor) {
+ console.log('No PR author found in environment variables');
+ return;
+ }
+
+ // Check if user should be excluded
+ if (EXCLUDED_USERS.includes(prAuthor)) {
+ console.log(`Skipping excluded user: ${prAuthor}`);
+ return;
+ }
+
+ console.log(`Processing contributor: ${prAuthor}`);
+
+ // Read package.json
+ let packageJson;
+ try {
+ const packageContent = fs.readFileSync(PACKAGE_JSON_PATH, 'utf8');
+ packageJson = JSON.parse(packageContent);
+ } catch (error) {
+ console.error('Error reading package.json:', error.message);
+ process.exit(1);
+ }
+
+ // Initialize contributors array if it doesn't exist
+ if (!packageJson.contributors) {
+ packageJson.contributors = [];
+ }
+
+ // Check if contributor is already listed
+ if (isContributorAlreadyListed(packageJson.contributors, prAuthor)) {
+ console.log(`Contributor ${prAuthor} is already listed`);
+ return;
+ }
+
+ // Try to get user email
+ const email = await getGitHubUserEmail(prAuthor);
+ const formattedContributor = formatContributor(prAuthor, email);
+
+ // Add new contributor
+ packageJson.contributors.push(formattedContributor);
+
+ // Sort contributors alphabetically (case-insensitive)
+ packageJson.contributors.sort((a, b) => {
+ const nameA = a.split(' ')[0].toLowerCase();
+ const nameB = b.split(' ')[0].toLowerCase();
+ return nameA.localeCompare(nameB);
+ });
+
+ // Write updated package.json
+ try {
+ fs.writeFileSync(PACKAGE_JSON_PATH, JSON.stringify(packageJson, null, 2) + '\n');
+ console.log(`Added ${formattedContributor} to contributors list`);
+ } catch (error) {
+ console.error('Error writing package.json:', error.message);
+ process.exit(1);
+ }
+}
+
+// Run the script
+updateContributors().catch(error => {
+ console.error('Script failed:', error.message);
+ process.exit(1);
+});
\ No newline at end of file
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 0000000..852655b
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,42 @@
+name: "CodeQL"
+
+on:
+ push:
+ branches: [ "main", "develop" ]
+ pull_request:
+ branches: [ "main", "develop" ]
+ schedule:
+ - cron: '0 0 * * 1' # Weekly on Mondays at midnight UTC
+
+jobs:
+ analyze:
+ name: Analyze
+ runs-on: ubuntu-latest
+ timeout-minutes: 360
+ permissions:
+ actions: read
+ contents: read
+ security-events: write
+
+ strategy:
+ fail-fast: false
+ matrix:
+ language: [ 'javascript' ]
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Initialize CodeQL
+ uses: github/codeql-action/init@v3
+ with:
+ languages: ${{ matrix.language }}
+ queries: security-extended,security-and-quality
+
+ - name: Autobuild
+ uses: github/codeql-action/autobuild@v3
+
+ - name: Perform CodeQL Analysis
+ uses: github/codeql-action/analyze@v3
+ with:
+ category: "/language:${{matrix.language}}"
diff --git a/.github/workflows/docx-diff.yml b/.github/workflows/docx-diff.yml
new file mode 100644
index 0000000..5a3e139
--- /dev/null
+++ b/.github/workflows/docx-diff.yml
@@ -0,0 +1,148 @@
+# TurboDocx DOCX Diff - Automated regression testing for HTML to DOCX conversion
+# Compares DOCX output between base branch and PR branch to catch regressions
+# Ensures consistent, high-quality document generation for html-to-docx library
+
+name: TurboDocx DOCX Diff Report
+
+on:
+ pull_request:
+ branches:
+ - main
+ - develop
+
+jobs:
+ docx-diff:
+ runs-on: ubuntu-latest
+ permissions:
+ pull-requests: write # Needed to post PR comments
+ contents: read
+
+ steps:
+ - name: Get PR details
+ id: pr
+ run: |
+ echo "base_ref=${{ github.event.pull_request.base.ref }}" >> $GITHUB_OUTPUT
+ echo "head_ref=${{ github.event.pull_request.head.ref }}" >> $GITHUB_OUTPUT
+
+ - name: Checkout base branch
+ uses: actions/checkout@v4
+ with:
+ ref: ${{ github.event.pull_request.base.sha }}
+ path: baseline
+
+ - name: Setup Node.js for baseline
+ uses: actions/setup-node@v4
+ with:
+ node-version: 18
+ cache: 'npm'
+ cache-dependency-path: baseline/package-lock.json
+
+ - name: Install dependencies (baseline)
+ working-directory: baseline
+ run: npm ci
+
+ - name: Generate baseline DOCX (HTML to DOCX conversion test)
+ working-directory: baseline
+ env:
+ DETERMINISTIC_IDS: 'true'
+ run: |
+ npm test
+ mv example-node.docx ../baseline.docx
+
+ - name: Checkout PR branch
+ uses: actions/checkout@v4
+ with:
+ path: current
+
+ - name: Setup Node.js for current
+ uses: actions/setup-node@v4
+ with:
+ node-version: 18
+ cache: 'npm'
+ cache-dependency-path: current/package-lock.json
+
+ - name: Install dependencies (current)
+ working-directory: current
+ run: npm ci
+
+ - name: Generate current DOCX (HTML to DOCX conversion test)
+ working-directory: current
+ env:
+ DETERMINISTIC_IDS: 'true'
+ run: |
+ npm test
+ mv example-node.docx ../current.docx
+
+ - name: Run TurboDocx DOCX diff analysis
+ id: diff
+ working-directory: current
+ run: |
+ node scripts/diff-docx.js ../baseline.docx ../current.docx --output ../diff-report.md || echo "diff_failed=true" >> $GITHUB_OUTPUT
+
+ - name: Read TurboDocx diff report
+ id: report
+ run: |
+ if [ -f diff-report.md ]; then
+ {
+ echo 'report<Document Header
"; + const docx = await HtmlToDocx(htmlString, headerHtml); +} + +// With document options +async function withOptions() { + const docx = await HtmlToDocx(htmlString, null, { + orientation: "landscape", + title: "TypeScript Example", + creator: "TurboDocx", + table: { + row: { + cantSplit: true, + }, + borderOptions: { + size: 1, + color: "000000" + } + }, + pageNumber: true, + footer: true + }); +} + +// With image processing options +async function withImageOptions() { + const htmlWithImages = `
+ Document Header
"; + const footerHtml = "Page Footer
"; + + const docx = await HtmlToDocx( + htmlString, + headerHtml, + { + orientation: "landscape", + pageSize: { + width: 12240, + height: 15840 + }, + margins: { + top: 1440, + right: 1800, + bottom: 1440, + left: 1800 + }, + title: "Complete Example", + creator: "TurboDocx", + }, + footerHtml + ); +} +``` + +For more comprehensive TypeScript examples, check out the following files in the `example/typescript` directory: + +- `typescript-example.ts` - A complete example showing how to generate and save DOCX files using TypeScript +- `type-test.ts` - Demonstrates the type checking capabilities provided by the TypeScript definitions + +### Running the TypeScript Examples + +To run the TypeScript examples: + +```bash +# Navigate to the example directory +cd example/typescript + +# Install ts-node globally (if not already installed) +npm install -g ts-node typescript + +# Ensure @turbodocx/html-to-docx is built and accessible +# From the root directory of the project: +# npm install +# npm run build + +# Run the TypeScript example directly +ts-node typescript-example.ts +``` + +This will generate two DOCX files in the `example/typescript` directory: +- `basic-example.docx` - A simple document with minimal configuration +- `advanced-example.docx` - A document with headers, footers, and advanced formatting options + ## Usage ```js @@ -66,6 +210,7 @@ full fledged examples can be found under `example/` - `size` denotes the border size. Defaults to `0`. - `stroke` denotes the style of the borderStrike. Defaults to `nil`. - `color` determines the border color. Defaults to `000000`. + - `addSpacingAfter` flag to add an empty paragraph after tables for spacing. Defaults to `true`. - `pageNumber` flag to enable page number in footer. Defaults to `false`. Page number works only if footer flag is set as `true`. - `skipFirstHeaderFooter` flag to skip first page header and footer. Defaults to `false`. - `lineNumber` flag to enable line numbering. Defaults to `false`. @@ -75,8 +220,36 @@ full fledged examples can be found under `example/` - `restart` <"continuous"|"newPage"|"newSection"> numbering restart strategy. Defaults to `continuous`. - `numbering` - `defaultOrderedListStyleType` default ordered list style type. Defaults to `decimal`. + - `heading` custom heading styles configuration + - `heading1`-`heading6` heading style configuration + - `font` font family + - `fontSize` font size in half-points + - `bold` whether text is bold. Defaults to `true` + - `spacing` paragraph spacing configuration + - `before` spacing before heading in twips + - `after` spacing after heading in twips + - `keepLines` keep lines together. Defaults to `true` + - `keepNext` keep with next paragraph. Defaults to `true` + - `outlineLevel` outline level (0-5) - `decodeUnicode` flag to enable unicode decoding of header, body and footer. Defaults to `false`. - `lang` language localization code for spell checker to work properly. Defaults to `en-US`. + - `direction` text direction for RTL (right-to-left) languages. Set to `'rtl'` for Arabic, Hebrew, etc. Defaults to `'ltr'`. + - `preProcessing` + - `skipHTMLMinify` flag to skip minification of HTML. Defaults to `false`. + - `imageProcessing` + - `maxRetries` maximum number of retry attempts for failed image downloads. Defaults to `2`. + - `verboseLogging` flag to enable detailed logging of image processing operations. Defaults to `false`. + - `downloadTimeout` timeout in milliseconds for each image download attempt. Defaults to `5000` (5 seconds). + - `maxImageSize` maximum allowed image size in bytes. Defaults to `10485760` (10MB). + - `retryDelayBase` base delay in milliseconds for exponential backoff between retries. Defaults to `500` (500ms). + - `minTimeout` minimum timeout in milliseconds. Defaults to `1000` (1 second). + - `maxTimeout` maximum timeout in milliseconds. Defaults to `30000` (30 seconds). + - `minImageSize` minimum image size in bytes. Defaults to `1024` (1KB). + - `maxCacheSize` maximum total cache size in bytes (LRU cache limit to prevent OOM). Defaults to `20971520` (20MB). + - `maxCacheEntries` maximum number of unique images in cache (LRU eviction). Defaults to `100`. + - `svgHandling` strategy for handling SVG images. Defaults to `'convert'`. Options: + - `'convert'` - Converts SVG to PNG for maximum compatibility with all Word versions (requires `sharp` package) + - `'native'` - Embeds SVG natively for Office 2019+ (preserves vector quality) - `footerHTMLString` <[String]> clean html string equivalent of footer. Defaults to `` if footer flag is `true`. ### Returns @@ -110,6 +283,151 @@ Also you could add attribute `data-start="n"` to start the numbering from the n- `
+ 
+ هذا نص تجريبي باللغة العربية ليظهر من اليمين إلى اليسار
+`; + +const docx = await HTMLtoDOCX(htmlString, null, { + direction: 'rtl', // Enable RTL text direction + lang: 'ar-SA', // Arabic locale (or 'he-IL' for Hebrew) + font: 'Arial', // Use a font that supports RTL characters +}); +``` + +For more RTL examples, check `example/react-example/src/example-rtl.js`. + +## Font Compatibility + Font family doesnt work consistently for all word processor softwares - Word Desktop work as intended @@ -156,4 +474,8 @@ MITThis heading uses a custom Arial font at 72pt (36pt in half-points) with extra spacing.
+ +This heading uses Georgia font at 40pt with custom spacing before and after.
+ +This heading uses a smaller font size and is not bold (unlike default).
+ +This heading uses the default styling to show the difference.
+ +This heading has minimal spacing and a specific outline level.
+ +This heading also uses default styling.
+ +All H1 tags will use the same custom style defined in the configuration.
+ +All H2 tags will use the same custom style.
+ +Demonstrating consistent styling across multiple headings of the same level.
+ +`; + +(async () => { + console.log('🎨 Creating DOCX with customizable heading styles...\n'); + + // Define custom heading styles + const customHeadingOptions = { + heading1: { + font: 'Arial', + fontSize: 72, // 36pt in Word (OOXML uses half-points: 72 / 2 = 36pt) + bold: true, + spacing: { + before: 600, // Spacing in twips (1/20 of a point) + after: 200, + }, + keepLines: true, + keepNext: true, + outlineLevel: 0, + }, + heading2: { + font: 'Georgia', + fontSize: 40, // 20pt in Word (40 / 2 = 20pt) + bold: true, + spacing: { + before: 400, + after: 150, + }, + keepLines: true, + keepNext: true, + outlineLevel: 1, + }, + heading3: { + font: 'Calibri', + fontSize: 26, // 13pt in Word (26 / 2 = 13pt) + bold: false, // Not bold (different from default) + spacing: { + before: 240, + after: 100, + }, + keepLines: true, + keepNext: true, + outlineLevel: 2, + }, + // heading4, heading5, heading6 will use default styles + heading5: { + font: 'Times New Roman', + fontSize: 20, // 10pt in Word (20 / 2 = 10pt) + bold: true, + spacing: { + before: 120, + after: 60, + }, + keepLines: false, // Allow splits + keepNext: false, + outlineLevel: 4, + }, + }; + + console.log('📋 Custom Heading Configuration:'); + console.log(' H1: Arial, 36pt, bold, extra spacing'); + console.log(' H2: Georgia, 20pt, bold, custom spacing'); + console.log(' H3: Calibri, 13pt, NOT bold, custom spacing'); + console.log(' H4: (using defaults)'); + console.log(' H5: Times New Roman, 10pt, bold, minimal spacing'); + console.log(' H6: (using defaults)\n'); + + try { + const fileBuffer = await HTMLtoDOCX(htmlString, null, { + heading: customHeadingOptions, + title: 'Customizable Heading Styles Demo', + subject: 'Demonstrating PR #129 - Customizable Heading Styles', + creator: 'TurboDocx Example', + description: 'This document showcases the customizable heading styles feature', + }); + + fs.writeFile(filePath, fileBuffer, (error) => { + if (error) { + console.log('❌ Docx file creation failed'); + console.error(error); + return; + } + console.log('✅ Docx file created successfully: ' + filePath); + console.log('\n📖 Open the file to see:'); + console.log(' • Custom fonts for different heading levels'); + console.log(' • Custom font sizes'); + console.log(' • Custom spacing before/after headings'); + console.log(' • H3 without bold (customized)'); + console.log(' • H4 and H6 with default styles (for comparison)'); + }); + } catch (error) { + console.log('❌ Error generating document'); + console.error(error); + } +})(); diff --git a/example/example-node.js b/example/example-node.js index fee93a0..6488115 100644 --- a/example/example-node.js +++ b/example/example-node.js @@ -4,7 +4,7 @@ const fs = require('fs'); // const HTMLtoDOCX = require('html-to-docx'); const HTMLtoDOCX = require('../dist/html-to-docx.umd'); -const filePath = './example.docx'; +const filePath = './example-node.docx'; const htmlString = ` @@ -23,6 +23,73 @@ const htmlString = ` src="https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png" alt="Red dot" /> + +Testing images with non-dimensional CSS styles (font-family, color):
+
+
+
+ Testing images with mixed dimensional and non-dimensional styles:
+
+
+ Testing images with various non-dimensional styles:
+
+
+
+
+ Testing SVG images (automatically converted to PNG for maximum compatibility):
+ +Simple SVG circle:
+
+
+ SVG with different sizes:
+
+
+
+ Inline SVG icon: SVG works inline too!
SVG bar chart:
+
+ + paragraph temporary lorem test tag +
+ Inside em tag
@@ -1642,21 +1724,345 @@ const htmlString = `
Table with empty row that could corrupt
+| Task | +Frequency | +
|---|---|
| Showroom | +|
| Wipe down display cars | +Daily | +
| Clean glass walls & windows | +Daily | +
| Mop & polish floors | +Daily | +
| Dust furniture & charging stations | +Daily | +
| Service Bay | +|
| Sweep & mop floors | +Daily | +
| Empty trash & oil disposal bins | +Daily | +
| Clean workbenches & tool areas | +Daily | +
| Wipe down customer drop-off zone | +Daily | +
| Waiting Area | +|
| Vacuum carpets & seating | +Daily | +
| Sanitize coffee station & touchscreens | +Daily | +
| Restock magazines & charging cables | +Daily | +
| Restrooms | +|
| Refill soap & paper products | +Daily | +
| Disinfect sinks & counters | +Daily | +
| Mop floors | +Daily | +
| Employee Lounge | +|
| Wipe tables & kitchen counters | +Daily | +
Testing for paragraph after table spacing if addSpacingAfterTable is true or false
+| Row 1, Col 1 | +Row 1, Col 2 | +
| Row 2, Col 1 | +Row 2, Col 2 | +
+ Mid Merge Border (No Space After Table) +
+Testing aspect ratio safety with zero/invalid dimensions:
+
+
+
+ Testing extreme aspect ratios:
+
+
+
+ Testing auto dimensions with CSS styles:
+
+
+ Testing images in figures (lineRule attribute fix):
+
+ Testing images with max-width/max-height constraints:
+
+
+ Testing images exceeding maximum document width (auto-scaling):
+
+ |
+ testset + |
+
+ test + |
+ |
|---|---|---|
|
+ data1 + |
+
+ data2 + |
+
+ data3 + |
+
These test cases verify that width and height HTML attributes are properly honored in DOCX generation:
+Test image original size: 5,807 × 2,817 pixels (8.35 MB JPEG)
+ +Test 1: Image with explicit width and height attributes (should render as 100x100):
+
+
+ Test 2: Image with only width attribute (height should maintain aspect ratio):
+
+
+ Test 3: Image with only height attribute (width should maintain aspect ratio):
+
+
+ Test 4: Image with width/height and additional styles (TinyMCE scenario):
+
+
+ Test 5: Image without dimensions (should use original image size - fallback behavior):
+
+
+ Test 6: Larger image with custom dimensions (demonstrates actual resize):
+
+
+ Test 7: Image with pixel units (explicit px):
+
+
+ Test 8: Image with point units (pt):
+
+
+ Test 9: Image with centimeter units (cm):
+
+
+ Test 10: Image with inch units (in):
+
+
+ Test 11: Image with percentage units (% of original size):
+
+
+ Test 12: Mixed units - width in cm, height in inches:
+
+