flexdoc

v1.9.0

Published

4 months ago

A flexible, lightweight npm library for converting HTML to PDF, PPTX, and DOCX formats with 25+ professional themes, automatic chart generation, and ML-based layout detection. Enterprise-ready with zero paid dependencies. Includes REST API server, cloud s

FlexDoc 📄

🎉 What's New in v1.9.0

Pro Tier Licensing System - Monetize your usage with Pro features!

🔑 JWT-Based Licensing: Secure, offline license validation with RSA signatures
⭐ Feature Gating: Pro features locked behind license validation
💎 Pro Features: Professional mode, 25+ premium themes, cloud storage, API server
📊 Tier System: Free, Pro ($49/mo), and Enterprise tiers
🛠️ Easy Activation: Environment variable, constructor, or .env file
📖 Comprehensive Docs: Full licensing documentation and examples
🔐 Secure: Offline validation, no API calls, cannot be forged

Get Pro License →

Previous: v1.8.0 - Major PPTX Enhancements

✨ Native Table Rendering: HTML tables → beautifully formatted PPTX tables
📋 Smart List Formatting: Bullet points and numbered lists with proper styling
🎯 Semantic HTML Support: <section> and <article> tags create slides automatically
🚀 Professional Mode Refactor: Removed Puppeteer dependency, 4x faster!

See full changelog →

🌟 Features

Core Capabilities

🚀 Multi-Format Support: Convert HTML to PDF, PPTX, and DOCX formats
🎯 Unified API: Single interface for all conversions with format-specific options
📦 Zero Paid Dependencies: Uses only open-source libraries (Puppeteer, pptxgenjs)
💪 Enterprise Ready: TypeScript support, error handling, and retry logic
🌐 Multiple Input Sources: HTML string, file path, or URL

PPTX Features ✨ NEW in v1.8.0

📊 Structured Content: Native tables, lists, and formatted text in slides
🎨 25+ Professional Themes: Beautiful pre-designed themes for presentations
🛠️ Custom Theme Builder: Create and save your own branded themes
📈 Auto Charts: Automatic table-to-chart conversion with smart type detection
🎭 Professional Mode: ML-powered layout optimization for Adobe-quality output
🔄 Smart Splitting: Automatic slide creation from sections, headings, or custom elements

PDF & DOCX Features

💧 PDF Watermarks: Text and image watermarks with full customization
📄 Word Documents: Full DOCX support with styling and formatting
🎨 Rich Formatting: Headers, footers, margins, and page layouts

Developer Experience

🖥️ CLI Tool: Powerful command-line interface for quick conversions
🔄 Batch Processing: Convert multiple documents simultaneously
🌩️ Cloud Storage: Direct upload to S3, Azure Blob, Google Drive
🔌 REST API Server: Docker-ready API with Swagger documentation
🤖 ML Layout Detection: Intelligent content analysis and optimization
⚙️ Highly Configurable: Extensive options for all formats

📦 Installation

npm install flexdoc

or with yarn:

yarn add flexdoc

🔑 Licensing & Pro Features

FlexDoc offers both Free and Pro tiers to suit different needs.

Free Tier (Open Source)

The free tier includes all core conversion features:

✅ HTML to PDF/PPTX/DOCX conversion
✅ 5 basic themes
✅ Standard conversion quality
✅ CLI and programmatic API
✅ Batch processing

Pro Tier ($49/month or $490/year)

Unlock advanced features for professional use:

⭐ Professional Mode: ML-powered layout optimization
🎨 25+ Premium Themes: Corporate, tech, creative, and more
☁️ Cloud Storage: Direct upload to S3, Azure, Google Drive
🔌 REST API Server: Production-ready API with authentication
💧 Advanced Watermarks: Complex watermark configurations
🏷️ Custom Branding: Remove "Generated by FlexDoc" attribution
🎯 Priority Support: Direct email support

Get Pro License →

Activating Your Pro License

Once you have a Pro license key, activate it in one of three ways:

Option 1: Environment Variable (Recommended for Production)

export FLEXDOC_LICENSE_KEY="your-license-key-here"

Option 2: Constructor (Recommended for Code)

const { FlexDoc } = require('flexdoc');

const flexdoc = new FlexDoc({
  licenseKey: 'your-license-key-here'
});

Option 3: .env File

FLEXDOC_LICENSE_KEY=your-license-key-here

Using Pro Features

const { FlexDoc } = require('flexdoc');

// Initialize with Pro license
const flexdoc = new FlexDoc({
  licenseKey: process.env.FLEXDOC_LICENSE_KEY
});

// Check license status
const license = flexdoc.getLicense();
console.log(`Tier: ${flexdoc.getLicenseTier()}`); // "pro"

// Use Professional Mode (Pro feature)
await flexdoc.toPPTX(html, {
  professional: true,  // ML-powered optimization
  outputPath: './presentation.pptx'
});

// Use Premium Themes (Pro feature)
await flexdoc.toPPTX(html, {
  theme: 'corporate-blue',  // Premium theme
  outputPath: './presentation.pptx'
});

// Upload to Cloud Storage (Pro feature)
await flexdoc.toPDF(html, {
  cloudOutput: 's3://my-bucket/document.pdf',
  cloudCredentials: {
    accessKeyId: 'YOUR_KEY',
    secretAccessKey: 'YOUR_SECRET'
  }
});

License Validation

const { LicenseValidator } = require('flexdoc');

const validator = new LicenseValidator();
const result = validator.validateLicense(licenseKey);

if (result.valid) {
  console.log('License is valid!');
  console.log(`Tier: ${result.license.tier}`);
  console.log(`Email: ${result.license.email}`);
  console.log(`Features: ${result.license.features.join(', ')}`);
} else {
  console.error(`Invalid license: ${result.error}`);
}

Free vs Pro Comparison

| Feature | Free | Pro | Enterprise | |---------|------|-----|------------| | HTML to PDF/PPTX/DOCX | ✅ | ✅ | ✅ | | Basic Themes (5) | ✅ | ✅ | ✅ | | Premium Themes (25+) | ❌ | ✅ | ✅ | | Professional Mode | ❌ | ✅ | ✅ | | Cloud Storage | ❌ | ✅ | ✅ | | REST API Server | ❌ | ✅ | ✅ | | Advanced Watermarks | ❌ | ✅ | ✅ | | Custom Branding | ❌ | ✅ | ✅ | | Priority Support | ❌ | ✅ | ✅ | | White Label | ❌ | ❌ | ✅ | | SLA Guarantee | ❌ | ❌ | ✅ | | Volume Licensing | ❌ | ❌ | ✅ |

Demo & Examples

Try the licensing demo:

npm run example:licensing

Or with a Pro license:

FLEXDOC_LICENSE_KEY="your-key" npm run example:licensing

🚀 Quick Start

Basic Usage

const { FlexDoc } = require('flexdoc');
// or ES6: import { FlexDoc } from 'flexdoc';

const flexdoc = new FlexDoc();

// Convert HTML to PDF
const pdfResult = await flexdoc.toPDF('<h1>Hello World</h1>', {
  outputPath: './output.pdf',
  format: 'A4'
});

// Convert HTML to PPTX (with structured content support)
const pptxResult = await flexdoc.toPPTX(`
  <section>
    <h1>Welcome</h1>
    <p>Introduction to our product</p>
  </section>
  <section>
    <h2>Key Features</h2>
    <ul>
      <li>Native table rendering</li>
      <li>Smart list formatting</li>
      <li>Professional styling</li>
    </ul>
  </section>
  <section>
    <h2>Performance Metrics</h2>
    <table>
      <tr><th>Metric</th><th>Value</th></tr>
      <tr><td>Speed</td><td>Fast</td></tr>
      <tr><td>Quality</td><td>High</td></tr>
    </table>
  </section>
`, {
  outputPath: './presentation.pptx',
  splitBy: 'section',  // Automatically creates slides from sections
  includeImages: true
});

// Convert HTML to DOCX
const docxResult = await flexdoc.toDOCX('<h1>My Document</h1><p>Content here</p>', {
  outputPath: './document.docx',
  orientation: 'portrait'
});

TypeScript Usage

import { FlexDoc, OutputFormat, PDFOptions, PPTXOptions } from 'flexdoc';

const flexdoc = new FlexDoc();

// With full type safety
const options: PDFOptions = {
  format: 'A4',
  printBackground: true,
  margin: {
    top: '2cm',
    bottom: '2cm'
  }
};

const result = await flexdoc.toPDF(htmlContent, options);

Professional Mode ✨ NEW

Use professional mode for Adobe-quality presentations with ML-powered layout optimization:

const { FlexDoc } = require('flexdoc');
const flexdoc = new FlexDoc();

const businessHTML = `
  <section>
    <h1>Q4 Business Review</h1>
    <p>Strategic insights and performance metrics</p>
  </section>
  <section>
    <h2>Financial Performance</h2>
    <table>
      <tr><th>Metric</th><th>Q3</th><th>Q4</th><th>Growth</th></tr>
      <tr><td>Revenue</td><td>$45M</td><td>$64M</td><td>+42%</td></tr>
      <tr><td>Customers</td><td>1,234</td><td>1,876</td><td>+52%</td></tr>
    </table>
  </section>
  <section>
    <h2>Key Initiatives</h2>
    <ul>
      <li>Product innovation and AI features</li>
      <li>International market expansion</li>
      <li>Enhanced customer success programs</li>
    </ul>
  </section>
`;

// Standard mode
const standard = await flexdoc.toPPTX(businessHTML, {
  outputPath: './standard-presentation.pptx',
  splitBy: 'section'
});

// Professional mode - ML-enhanced with better layouts
const professional = await flexdoc.toPPTX(businessHTML, {
  professional: true,  // Enable Adobe-quality mode
  outputPath: './professional-presentation.pptx',
  theme: 'corporate',  // Or 'creative', 'minimal', 'tech'
  splitBy: 'section',
  includeImages: true
});

console.log(`Created ${professional.metadata.slideCount} slides`);
console.log(`Quality: ${professional.metadata.quality}`); // "professional"

What's Different in Professional Mode?

✅ ML-powered content analysis
✅ Intelligent layout optimization
✅ Enhanced visual hierarchy
✅ Better spacing and positioning
✅ Professional metadata markers
✅ No browser overhead (fast!)

🖥️ CLI Usage

FlexDoc includes a powerful command-line interface for quick conversions.

Installation

After installing FlexDoc globally or in your project, the flexdoc command becomes available:

# Global installation
npm install -g flexdoc

# Or use with npx (no installation needed)
npx flexdoc --help

Commands

Convert to PDF

# Basic usage
flexdoc pdf input.html -o output.pdf

# With options
flexdoc pdf input.html \
  --output document.pdf \
  --format A4 \
  --landscape \
  --margin-top 2cm \
  --margin-bottom 2cm

# From URL
flexdoc pdf https://example.com -o webpage.pdf

# With custom CSS
flexdoc pdf input.html --css styles.css -o styled.pdf

# With header and footer
flexdoc pdf input.html \
  --header "<div>My Header</div>" \
  --footer "<div>Page <span class='pageNumber'></span></div>" \
  -o document.pdf

# With watermark
flexdoc pdf document.html \
  --watermark-text "CONFIDENTIAL" \
  --watermark-position diagonal \
  --watermark-opacity 0.3 \
  -o confidential.pdf

PDF Options:

-o, --output <path> - Output file path (default: output.pdf)
-f, --format <format> - Paper format: A4, A3, Letter, Legal, Tabloid (default: A4)
-l, --landscape - Landscape orientation
--margin-top <size> - Top margin (default: 1cm)
--margin-right <size> - Right margin (default: 1cm)
--margin-bottom <size> - Bottom margin (default: 1cm)
--margin-left <size> - Left margin (default: 1cm)
--scale <number> - Scale factor 0.1 to 2.0 (default: 1)
--header <template> - HTML header template
--footer <template> - HTML footer template
--no-background - Disable background graphics
--css <file> - Custom CSS file to inject
--wait <selector> - Wait for CSS selector before conversion
--watermark-text <text> - Watermark text
--watermark-image <path> - Watermark image file path
--watermark-position <position> - Watermark position: center, diagonal, top-left, top-right, bottom-left, bottom-right, top-center, bottom-center (default: center)
--watermark-opacity <number> - Watermark opacity 0-1 (default: 0.3)
--watermark-font-size <number> - Watermark font size (default: 72)
--watermark-color <color> - Watermark color (default: #000000)
--watermark-rotation <degrees> - Watermark rotation in degrees (default: 0)
--watermark-repeat - Repeat watermark across page
--debug - Enable debug mode

Convert to PPTX

# Basic usage
flexdoc pptx input.html -o presentation.pptx

# With options
flexdoc pptx input.html \
  --output slides.pptx \
  --layout 16x9 \
  --split h1 \
  --title "My Presentation" \
  --author "John Doe" \
  --theme corporate

# From URL
flexdoc pptx https://example.com/slides -o presentation.pptx

# With custom settings
flexdoc pptx content.html \
  --split h2 \
  --theme dark \
  --max-content 300 \
  --no-images

PPTX Options:

-o, --output <path> - Output file path (default: output.pptx)
-l, --layout <layout> - Slide layout: 16x9, 16x10, 4x3 (default: 16x9)
-s, --split <element> - Split slides by: h1, h2, h3, hr (default: h2)
-t, --title <title> - Presentation title
-a, --author <author> - Presentation author
-c, --company <company> - Company name
--theme <theme> - Theme: default, dark, corporate, creative (default: default)
--no-images - Exclude images from slides
--max-content <chars> - Max characters per slide (default: 500)
--no-auto-charts - Disable automatic chart generation from tables
--chart-types <types> - Preferred chart types (comma-separated: bar,line,pie,area,scatter)
--chart-position <position> - Chart position: replace, alongside, both (default: replace)
--css <file> - Custom CSS file to inject
--debug - Enable debug mode

Convert to DOCX

# Basic usage
flexdoc docx input.html -o document.docx

# With options
flexdoc docx input.html \
  --output report.docx \
  --orientation portrait \
  --page-size A4 \
  --title "Annual Report" \
  --author "John Doe"

# From URL
flexdoc docx https://example.com -o webpage.docx

# With header and footer
flexdoc docx content.html \
  --header "Company Confidential" \
  --footer "Page {PAGE} of {TOTAL}" \
  -o document.docx

# With table of contents
flexdoc docx document.html \
  --toc \
  --toc-title "Table of Contents" \
  -o report.docx

# With custom fonts and spacing
flexdoc docx content.html \
  --font-family "Calibri" \
  --font-size 12 \
  --line-spacing 1.5 \
  --theme corporate \
  -o styled.docx

DOCX Options:

-o, --output <path> - Output file path (default: output.docx)
--orientation <orientation> - Page orientation: portrait, landscape (default: portrait)
--page-size <size> - Page size: A4, Letter, Legal, A3, Tabloid (default: A4)
-t, --title <title> - Document title
-a, --author <author> - Document author
-c, --company <company> - Company name
--theme <theme> - Document theme: default, professional, modern, classic (default: default)
--header <text> - Header text (supports {PAGE} and {TOTAL} placeholders)
--footer <text> - Footer text (supports {PAGE} and {TOTAL} placeholders)
--toc - Generate table of contents
--toc-title <title> - Table of contents title (default: "Table of Contents")
--font-family <font> - Font family (default: Arial)
--font-size <size> - Font size in points (default: 11)
--line-spacing <spacing> - Line spacing multiplier (default: 1.15)
--margin-top <size> - Top margin (default: 1in)
--margin-right <size> - Right margin (default: 1in)
--margin-bottom <size> - Bottom margin (default: 1in)
--margin-left <size> - Left margin (default: 1in)
--no-images - Exclude images from document
--css <file> - Custom CSS file to inject
--debug - Enable debug mode

Batch Conversion

Convert multiple files using a JSON configuration:

flexdoc batch config.json

Example config.json:

{
  "items": [
    {
      "input": "report.html",
      "format": "pdf",
      "options": {
        "outputPath": "output/report.pdf",
        "format": "A4",
        "printBackground": true
      }
    },
    {
      "input": "slides.html",
      "format": "pptx",
      "options": {
        "outputPath": "output/presentation.pptx",
        "layout": "16x9",
        "theme": "corporate"
      }
    }
  ]
}

System Information

flexdoc info

Shows FlexDoc version, Node.js version, and supported formats.

CLI Examples

# Convert HTML file to PDF with custom margins
flexdoc pdf document.html -o report.pdf --margin-top 3cm --margin-bottom 3cm

# Convert webpage to landscape PDF
flexdoc pdf https://github.com -o github.pdf --landscape --format Letter

# Add diagonal confidential watermark
flexdoc pdf report.html --watermark-text "CONFIDENTIAL" --watermark-position diagonal --watermark-opacity 0.2 -o secure.pdf

# Add image watermark
flexdoc pdf document.html --watermark-image logo.png --watermark-position bottom-right --watermark-opacity 0.5 -o branded.pdf

# Create presentation from HTML with custom theme
flexdoc pptx content.html -o slides.pptx --theme dark --split h1 --title "Q4 Report"

# Create presentation with automatic charts from tables
flexdoc pptx data.html -o charts.pptx --theme corporate --chart-types bar,line

# Disable automatic chart generation (keep tables)
flexdoc pptx data.html -o tables.pptx --no-auto-charts

# Create Word document with header and footer
flexdoc docx report.html -o report.docx --header "Annual Report 2024" --footer "Page {PAGE}"

# Create Word document with table of contents
flexdoc docx documentation.html -o docs.docx --toc --theme professional

# Batch convert multiple documents
flexdoc batch conversions.json --debug

# Get help for a specific command
flexdoc pdf --help
flexdoc pptx --help
flexdoc docx --help

📖 API Documentation

Main Class: `FlexDoc`

Methods

`toPDF(html, options?)`

Convert HTML to PDF format.

const result = await flexdoc.toPDF(html, {
  outputPath: './document.pdf',
  format: 'A4',
  printBackground: true,
  margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' },
  landscape: false,
  scale: 1,
  displayHeaderFooter: true,
  headerTemplate: '<div>Header</div>',
  footerTemplate: '<div>Page <span class="pageNumber"></span></div>'
});

`toPPTX(html, options?)`

Convert HTML to PowerPoint presentation.

const result = await flexdoc.toPPTX(html, {
  outputPath: './presentation.pptx',
  layout: '16x9',
  splitBy: 'h2',
  title: 'My Presentation',
  author: 'John Doe',
  theme: 'corporate'
});

`toDOCX(html, options?)`

Convert HTML to Word document.

const result = await flexdoc.toDOCX(html, {
  outputPath: './document.docx',
  orientation: 'portrait',
  pageSize: 'A4',
  title: 'My Document',
  author: 'John Doe',
  theme: 'professional'
});

`convert(html, options)`

Unified API for all formats.

const result = await flexdoc.convert(html, {
  format: OutputFormat.PDF, // or OutputFormat.PPTX, OutputFormat.DOCX
  outputPath: './output.pdf',
  pdfOptions: { /* PDF-specific options */ },
  pptxOptions: { /* PPTX-specific options */ },
  docxOptions: { /* DOCX-specific options */ }
});

`convertBatch(items)`

Process multiple conversions.

const results = await flexdoc.convertBatch([
  { html: content1, format: OutputFormat.PDF, options: { format: 'A4' } },
  { html: content2, format: OutputFormat.PPTX, options: { layout: '16x9' } }
]);

Input Options

FlexDoc accepts HTML in multiple formats:

// 1. HTML String
await flexdoc.toPDF('<h1>Hello</h1>');

// 2. File Path
await flexdoc.toPDF({ filePath: './document.html' });

// 3. URL
await flexdoc.toPDF({ url: 'https://example.com' });

// 4. HTML Content Object
await flexdoc.toPDF({ content: '<h1>Hello</h1>' });

PDF Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | format | string | 'A4' | Paper format (A4, A3, Letter, etc.) | | width | string/number | - | Custom page width | | height | string/number | - | Custom page height | | margin | object | {top:'1cm',...} | Page margins | | printBackground | boolean | true | Print background graphics | | landscape | boolean | false | Landscape orientation | | scale | number | 1 | Scale of rendering (0.1 to 2.0) | | displayHeaderFooter | boolean | false | Display header and footer | | headerTemplate | string | - | HTML template for header | | footerTemplate | string | - | HTML template for footer | | pageRanges | string | - | Page ranges to print | | preferCSSPageSize | boolean | false | Use CSS-defined page size |

PPTX Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | layout | string | '16x9' | Slide layout (16x9, 16x10, 4x3) | | slideWidth | number | 10 | Slide width in inches | | slideHeight | number | 5.625 | Slide height in inches | | splitBy | string | 'h2' | Element to split slides by | | title | string | - | Presentation title | | author | string | - | Presentation author | | company | string | - | Company name | | theme | string | 'default' | Presentation theme (default, dark, corporate, creative) | | includeImages | boolean | true | Include images from HTML | | maxContentPerSlide | number | 500 | Max characters per slide (auto-split) |

DOCX Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | orientation | string | 'portrait' | Page orientation (portrait, landscape) | | pageSize | string | 'A4' | Page size (A4, Letter, Legal, A3, Tabloid) | | pageWidth | number | - | Custom page width (overrides pageSize) | | pageHeight | number | - | Custom page height (overrides pageSize) | | margins | object | {top:1440,...} | Page margins in twips (1 inch = 1440 twips) | | title | string | - | Document title | | author | string | - | Document author | | company | string | - | Company name | | subject | string | - | Document subject | | keywords | string | - | Document keywords | | theme | string | 'default' | Document theme (default, professional, modern, classic) | | fontFamily | string | 'Arial' | Default font family | | fontSize | number | 11 | Default font size in points | | lineSpacing | number | 1.15 | Line spacing multiplier | | includeImages | boolean | true | Include images from HTML | | header | object/string | - | Header configuration or text | | footer | object/string | - | Footer configuration or text | | tableOfContents | boolean/object | false | Generate table of contents | | tocTitle | string | 'Table of Contents' | TOC title | | numbering | boolean | false | Enable heading numbering | | styles | object | - | Custom styles configuration |

Common Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | outputPath | string | - | Output file path | | debug | boolean | false | Enable debug logging | | timeout | number | 30000 | Timeout in milliseconds | | onProgress | function | - | Progress callback | | customCSS | string | - | Custom CSS to inject | | executeScript | string | - | JavaScript to execute | | waitForSelector | string | - | Wait for element before conversion |

📝 Examples

Convert a Website to PDF

const result = await flexdoc.toPDF({
  url: 'https://github.com'
}, {
  outputPath: './github.pdf',
  format: 'A4',
  printBackground: true
});

Create a Presentation from HTML

const html = `
  <h1>Introduction</h1>
  <p>Welcome to our presentation</p>

  <h1>Features</h1>
  <ul>
    <li>Feature 1</li>
    <li>Feature 2</li>
  </ul>

  <h1>Conclusion</h1>
  <p>Thank you!</p>
`;

const result = await flexdoc.toPPTX(html, {
  outputPath: './slides.pptx',
  splitBy: 'h1',
  theme: 'corporate'
});

Automatic Chart Generation from Tables

FlexDoc can automatically convert HTML tables into beautiful charts in presentations:

const html = `
  <h1>Quarterly Sales Report</h1>
  <table>
    <tr>
      <th>Region</th>
      <th>Q1</th>
      <th>Q2</th>
      <th>Q3</th>
      <th>Q4</th>
    </tr>
    <tr>
      <td>North America</td>
      <td>125000</td>
      <td>132000</td>
      <td>145000</td>
      <td>158000</td>
    </tr>
    <tr>
      <td>Europe</td>
      <td>98000</td>
      <td>105000</td>
      <td>112000</td>
      <td>120000</td>
    </tr>
  </table>
`;

// Tables automatically convert to charts
await flexdoc.toPPTX(html, {
  outputPath: './sales-charts.pptx',
  autoCharts: true, // Enabled by default
  theme: 'corporate'
});

// Customize chart preferences
await flexdoc.toPPTX(html, {
  outputPath: './custom-charts.pptx',
  autoCharts: true,
  chartOptions: {
    preferredTypes: ['bar', 'line'], // Prefer specific chart types
    minRows: 3, // Minimum rows to generate chart
    maxRows: 50, // Maximum rows for chart
    showValues: true, // Show data values on chart
    showLegend: true, // Show chart legend
    theme: 'colorful', // Chart theme
    position: 'replace' // 'replace', 'alongside', or 'both'
  }
});

// Disable auto-charts (keep tables)
await flexdoc.toPPTX(html, {
  outputPath: './with-tables.pptx',
  autoCharts: false
});

Smart Chart Detection:

Bar Charts: Multi-series comparison data
Line Charts: Time series data (years, months, quarters)
Pie Charts: Single-series data with few categories (≤8)
Area Charts: Large datasets (>20 points)
Scatter Charts: Correlation data (2 numeric columns)

Professional Themes for Presentations

FlexDoc includes 25+ professional themes and a powerful theme builder:

// Use a preset theme
await flexdoc.toPPTX(html, {
  outputPath: './corporate.pptx',
  theme: 'corporate-blue' // or 'tech-purple', 'creative-pink', etc.
});

// Create a custom theme
const { ThemeBuilder } = require('flexdoc');

const myTheme = new ThemeBuilder('My Brand')
  .setPrimaryColor('#6366F1')
  .setFontPairing('Modern Professional')
  .setShadows(true)
  .setGradients(true)
  .build();

await flexdoc.toPPTX(html, {
  outputPath: './branded.pptx',
  theme: myTheme
});

// Quick customization
await flexdoc.toPPTX(html, {
  outputPath: './custom.pptx',
  theme: 'corporate-blue',
  themeOptions: {
    primaryColor: '#DB2777', // Override primary color
    enableEffects: true
  }
});

// Save and load themes
const { ThemeManager } = require('flexdoc');

// Save theme to file
ThemeManager.saveThemeToFile(myTheme, './my-theme.json');

// Load from file
const loadedTheme = ThemeManager.loadThemeFromFile('./my-theme.json');
await flexdoc.toPPTX(html, { theme: loadedTheme });

// List all available themes
const themes = ThemeManager.listPresets();
console.log(`Available themes: ${themes.length}`);

Available Theme Categories:

Business (5 themes): corporate-blue, professional-gray, executive-gold, financial-green, consulting-navy
Tech (5 themes): tech-purple, startup-orange, innovation-teal, digital-cyan, saas-modern
Creative (5 themes): creative-pink, designer-vibrant, artistic-rainbow, modern-minimal, bold-impact
Academic (3 themes): academic-serif, education-friendly, scientific-clean
Special (7 themes): dark-mode, high-contrast, print-optimized, elegant-luxury, playful-fun, nature-green, ocean-blue

Theme Builder Features:

Color harmony generation (complementary, analogous, triadic, monochromatic)
Smart font pairings (17 curated combinations)
Dark mode conversion
Accessibility validation (WCAG compliance)
Complete customization of colors, typography, layout, and effects

CLI Theme Support:

# List all themes
flexdoc themes

# Use a preset theme
flexdoc pptx input.html --theme tech-purple

# Use custom theme file
flexdoc pptx input.html --theme-file my-theme.json

# Quick color override
flexdoc pptx input.html --theme corporate-blue --primary-color "#DB2777"

Add Watermarks to PDFs

// Text watermark
await flexdoc.toPDF(html, {
  outputPath: './confidential.pdf',
  watermark: {
    text: 'CONFIDENTIAL',
    position: 'diagonal',  // or 'center', 'top-left', 'top-right', etc.
    opacity: 0.2,
    fontSize: 80,
    color: '#FF0000'
  }
});

// Image watermark
await flexdoc.toPDF(html, {
  outputPath: './branded.pdf',
  watermark: {
    image: './logo.png',
    position: 'bottom-right',
    opacity: 0.5,
    imageWidth: 100,
    imageHeight: 100
  }
});

// Repeating watermark pattern
await flexdoc.toPDF(html, {
  outputPath: './draft.pdf',
  watermark: {
    text: 'DRAFT',
    repeat: true,
    opacity: 0.1,
    fontSize: 40
  }
});

// Custom styled watermark
await flexdoc.toPDF(html, {
  outputPath: './sample.pdf',
  watermark: {
    text: 'SAMPLE',
    position: 'center',
    opacity: 0.3,
    fontSize: 72,
    color: '#3498db',
    rotation: -45,
    fontFamily: 'Arial Black',
    fontWeight: 'bold'
  }
});

Watermark Options:

text - Watermark text
image - Path to watermark image
position - Placement: center, diagonal, top-left, top-right, bottom-left, bottom-right, top-center, bottom-center
opacity - Transparency (0-1)
fontSize - Font size for text watermarks
color - Text color (hex or named)
rotation - Rotation angle in degrees
repeat - Repeat across entire page
fontFamily - Font family for text
fontWeight - Font weight
imageWidth / imageHeight - Image dimensions

Word Document (DOCX) Conversion

FlexDoc provides comprehensive Word document generation with professional formatting, themes, headers/footers, table of contents, and more.

Basic DOCX Conversion

const { FlexDoc } = require('flexdoc');
const flexdoc = new FlexDoc();

// Simple document
await flexdoc.toDOCX('<h1>My Document</h1><p>Content here</p>', {
  outputPath: './document.docx'
});

// From file
await flexdoc.toDOCX({ filePath: './content.html' }, {
  outputPath: './output.docx',
  orientation: 'portrait',
  pageSize: 'A4'
});

// From URL
await flexdoc.toDOCX({ url: 'https://example.com/article' }, {
  outputPath: './article.docx'
});

DOCX with Professional Themes

FlexDoc includes 25+ professional themes optimized for Word documents:

// Use a preset theme
await flexdoc.toDOCX(html, {
  outputPath: './professional.docx',
  theme: 'professional' // or 'modern', 'classic', 'elegant', 'corporate'
});

// Corporate theme with custom branding
await flexdoc.toDOCX(html, {
  outputPath: './branded.docx',
  theme: 'corporate',
  themeOptions: {
    primaryColor: '#0066CC',
    accentColor: '#FF6B35'
  }
});

// Modern minimalist theme
await flexdoc.toDOCX(html, {
  outputPath: './modern.docx',
  theme: 'modern',
  fontFamily: 'Calibri',
  fontSize: 11,
  lineSpacing: 1.15
});

Available Document Themes:

Professional: Clean, business-oriented design with serif fonts
Modern: Contemporary look with sans-serif fonts and subtle colors
Classic: Traditional academic style with Times New Roman
Corporate: Bold headings with structured formatting
Elegant: Sophisticated design with refined typography
Technical: Code-friendly with monospace support
Creative: Vibrant colors and unique formatting
Minimalist: Clean and simple design

Headers and Footers with Page Numbers

// Simple header and footer
await flexdoc.toDOCX(html, {
  outputPath: './document.docx',
  header: 'Company Confidential',
  footer: 'Page {PAGE} of {TOTAL}'
});

// Advanced header/footer configuration
await flexdoc.toDOCX(html, {
  outputPath: './report.docx',
  header: {
    text: 'Annual Report 2024',
    alignment: 'center',
    fontSize: 10,
    color: '#666666'
  },
  footer: {
    left: '© 2024 Company Inc.',
    center: 'Confidential',
    right: 'Page {PAGE} of {TOTAL}'
  }
});

// Different header/footer for first page
await flexdoc.toDOCX(html, {
  outputPath: './custom.docx',
  header: {
    default: 'Company Name - Internal Report',
    firstPage: '' // No header on first page
  },
  footer: {
    default: 'Page {PAGE}',
    firstPage: 'Copyright © 2024'
  }
});

// With logo in header
await flexdoc.toDOCX(html, {
  outputPath: './branded.docx',
  header: {
    image: './logo.png',
    imageWidth: 100,
    imageHeight: 50,
    alignment: 'right',
    text: 'Company Name'
  },
  footer: 'Page {PAGE} of {TOTAL}'
});

Table of Contents Generation

// Basic table of contents
await flexdoc.toDOCX(html, {
  outputPath: './documentation.docx',
  tableOfContents: true,
  tocTitle: 'Table of Contents'
});

// Advanced TOC configuration
await flexdoc.toDOCX(html, {
  outputPath: './report.docx',
  tableOfContents: {
    enabled: true,
    title: 'Contents',
    includePageNumbers: true,
    includeLinks: true,
    maxDepth: 3, // Include h1, h2, h3
    style: 'professional' // or 'simple', 'detailed'
  }
});

// TOC with custom styling
await flexdoc.toDOCX(html, {
  outputPath: './styled-toc.docx',
  tableOfContents: {
    enabled: true,
    title: 'Table of Contents',
    fontSize: 14,
    fontFamily: 'Calibri',
    alignment: 'left',
    showDots: true, // Leader dots
    rightAlign: true // Right-align page numbers
  }
});

Custom Typography and Spacing

// Custom fonts and spacing
await flexdoc.toDOCX(html, {
  outputPath: './custom.docx',
  fontFamily: 'Calibri',
  fontSize: 12,
  lineSpacing: 1.5,
  margins: {
    top: 2880,    // 2 inches (1440 twips = 1 inch)
    right: 1440,  // 1 inch
    bottom: 2880, // 2 inches
    left: 1440    // 1 inch
  }
});

// Heading-specific styling
await flexdoc.toDOCX(html, {
  outputPath: './styled.docx',
  styles: {
    heading1: {
      fontSize: 24,
      fontFamily: 'Arial',
      bold: true,
      color: '#1a1a1a',
      spacing: { before: 480, after: 240 }
    },
    heading2: {
      fontSize: 18,
      fontFamily: 'Arial',
      bold: true,
      color: '#333333',
      spacing: { before: 360, after: 180 }
    },
    paragraph: {
      fontSize: 11,
      fontFamily: 'Calibri',
      lineSpacing: 1.15,
      alignment: 'justify'
    }
  }
});

// Professional report formatting
await flexdoc.toDOCX(html, {
  outputPath: './report.docx',
  fontFamily: 'Georgia',
  fontSize: 11,
  lineSpacing: 1.5,
  firstLineIndent: 720, // 0.5 inch
  paragraphSpacing: {
    before: 120,
    after: 120
  }
});

Page Orientation and Sizes

// Portrait A4 (default)
await flexdoc.toDOCX(html, {
  outputPath: './portrait.docx',
  orientation: 'portrait',
  pageSize: 'A4'
});

// Landscape Letter
await flexdoc.toDOCX(html, {
  outputPath: './landscape.docx',
  orientation: 'landscape',
  pageSize: 'Letter'
});

// Custom page dimensions
await flexdoc.toDOCX(html, {
  outputPath: './custom.docx',
  pageWidth: 8.5,  // inches
  pageHeight: 14,  // inches (Legal size)
  orientation: 'portrait'
});

// Multiple page sizes (supports A4, Letter, Legal, A3, Tabloid)
await flexdoc.toDOCX(html, {
  outputPath: './legal.docx',
  pageSize: 'Legal',
  margins: {
    top: 1440,
    right: 1440,
    bottom: 1440,
    left: 1440
  }
});

Complete Document Example

const html = `
  <h1>Annual Report 2024</h1>

  <h2>Executive Summary</h2>
  <p>This report provides a comprehensive overview of our company's performance in 2024...</p>

  <h2>Financial Performance</h2>
  <h3>Revenue Growth</h3>
  <p>Our revenue increased by 25% year-over-year...</p>

  <table>
    <tr><th>Quarter</th><th>Revenue</th><th>Growth</th></tr>
    <tr><td>Q1</td><td>$2.5M</td><td>15%</td></tr>
    <tr><td>Q2</td><td>$3.2M</td><td>28%</td></tr>
    <tr><td>Q3</td><td>$3.8M</td><td>32%</td></tr>
    <tr><td>Q4</td><td>$4.1M</td><td>35%</td></tr>
  </table>

  <h2>Conclusion</h2>
  <p>Looking forward to continued growth in 2025...</p>
`;

await flexdoc.toDOCX(html, {
  outputPath: './annual-report-2024.docx',

  // Document metadata
  title: 'Annual Report 2024',
  author: 'John Doe',
  company: 'Acme Corporation',
  subject: 'Financial Performance Review',
  keywords: 'annual report, finance, 2024, performance',

  // Page setup
  orientation: 'portrait',
  pageSize: 'A4',
  margins: {
    top: 2880,    // 2 inches
    right: 1440,  // 1 inch
    bottom: 2880,
    left: 1440
  },

  // Theme and styling
  theme: 'professional',
  fontFamily: 'Calibri',
  fontSize: 11,
  lineSpacing: 1.15,

  // Headers and footers
  header: {
    text: 'Annual Report 2024 - Confidential',
    alignment: 'center',
    fontSize: 9,
    color: '#666666'
  },
  footer: {
    left: '© 2024 Acme Corporation',
    center: '',
    right: 'Page {PAGE} of {TOTAL}'
  },

  // Table of contents
  tableOfContents: {
    enabled: true,
    title: 'Table of Contents',
    includePageNumbers: true,
    includeLinks: true,
    maxDepth: 3
  },

  // Images
  includeImages: true,

  // Custom styles
  styles: {
    heading1: {
      fontSize: 20,
      bold: true,
      color: '#1a472a',
      spacing: { before: 480, after: 240 }
    },
    heading2: {
      fontSize: 16,
      bold: true,
      color: '#2c5f2d',
      spacing: { before: 360, after: 180 }
    }
  }
});

CLI Examples for DOCX

# Basic conversion
flexdoc docx report.html -o report.docx

# With theme and formatting
flexdoc docx content.html \
  --output professional.docx \
  --theme professional \
  --font-family "Calibri" \
  --font-size 11 \
  --line-spacing 1.5

# With header and footer
flexdoc docx article.html \
  --output article.docx \
  --header "My Article" \
  --footer "Page {PAGE} of {TOTAL}" \
  --page-size Letter

# With table of contents
flexdoc docx documentation.html \
  --output docs.docx \
  --toc \
  --toc-title "Documentation Index" \
  --theme modern

# Landscape orientation
flexdoc docx wide-content.html \
  --output landscape.docx \
  --orientation landscape \
  --page-size A4

# Complete example with all options
flexdoc docx report.html \
  --output comprehensive-report.docx \
  --title "Annual Report 2024" \
  --author "John Doe" \
  --company "Acme Corp" \
  --theme corporate \
  --orientation portrait \
  --page-size A4 \
  --header "Annual Report 2024 - Confidential" \
  --footer "Page {PAGE} of {TOTAL}" \
  --toc \
  --font-family "Calibri" \
  --font-size 12 \
  --line-spacing 1.5 \
  --margin-top 2in \
  --margin-bottom 2in

Progress Tracking

await flexdoc.toPDF(html, {
  outputPath: './document.pdf',
  onProgress: (progress) => {
    console.log(`${progress.percentage}% - ${progress.step}`);
  }
});

Custom Styling and Scripts

await flexdoc.toPDF(html, {
  customCSS: `
    body { font-family: 'Helvetica', sans-serif; }
    .highlight { background-color: yellow; }
  `,
  executeScript: `
    document.querySelectorAll('h1').forEach(h => {
      h.style.color = 'blue';
    });
  `,
  waitForSelector: '.dynamic-content'
});

Error Handling

try {
  const result = await flexdoc.toPDF(html, options);
  if (result.success) {
    console.log('Conversion successful!');
    console.log('File size:', result.size);
    console.log('Duration:', result.duration, 'ms');
  }
} catch (error) {
  if (error.type === 'VALIDATION_ERROR') {
    console.error('Invalid options:', error.message);
  } else if (error.type === 'CONVERSION_FAILED') {
    console.error('Conversion failed:', error.message);
  }
}

Batch Processing

const documents = [
  { content: '<h1>Doc 1</h1>', name: 'doc1.pdf' },
  { content: '<h1>Doc 2</h1>', name: 'doc2.pdf' },
  { content: '<h1>Doc 3</h1>', name: 'doc3.pptx' }
];

const inputs = documents.map(doc => ({
  html: doc.content,
  format: doc.name.endsWith('.pdf') ? OutputFormat.PDF : OutputFormat.PPTX,
  options: {
    outputPath: `./output/${doc.name}`
  }
}));

const results = await flexdoc.convertBatch(inputs);
console.log(`Converted ${results.successful} of ${results.total} documents`);

🏗️ Architecture

FlexDoc is built with a modular architecture:

flexdoc/
├── src/
│   ├── index.ts           # Main FlexDoc class
│   ├── types.ts           # TypeScript definitions
│   ├── converters/        # PDF and PPTX converters
│   │   ├── pdf-converter.ts
│   │   ├── pptx-converter.ts
│   │   ├── enhanced-pptx-converter.ts
│   │   └── professional-pptx-converter.ts
│   ├── engines/           # Processing engines
│   │   ├── chart-engine.ts
│   │   ├── image-processing-engine.ts
│   │   └── ai-layout-engine.ts
│   └── utils/             # Utility functions
│       ├── validators.ts
│       └── file-handler.ts

🧪 Testing

Run tests with:

npm test

Run examples:

npm run example
npm run example:pdf
npm run example:pptx

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

How to Contribute

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/rakeshwfg/flexdoc.git
cd flexdoc

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build
npm run build

Contribution Guidelines

Write clear, concise commit messages
Add tests for new features
Update documentation as needed
Follow the existing code style
Ensure all tests pass before submitting PR

💖 Support This Project

If FlexDoc has helped you or your organization, consider supporting its development!

☕ Buy Me a Coffee

Your support helps maintain and improve FlexDoc:

⭐ Star this repository on GitHub
💝 Sponsor on GitHub: Become a sponsor
☕ Buy me a coffee: ko-fi.com/rakeshsingh16
💳 One-time donation: PayPal

🌟 Other Ways to Support

📢 Share FlexDoc with your network
🐛 Report bugs and suggest features
📝 Write blog posts or tutorials about FlexDoc
💻 Contribute code, documentation, or examples
💬 Help others in GitHub discussions

🏢 Enterprise Support

Need dedicated support, custom features, or consulting?

📧 Email: [email protected]
🔗 LinkedIn: Rakesh Singh
💼 Custom development and integration services available

🙏 Thank You!

Every contribution, no matter how small, makes a difference. Thank you for supporting open source!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Puppeteer for PDF generation
PptxGenJS for PPTX creation
jsdom for HTML parsing
html-to-text for text extraction
Sharp for image processing

📞 Support

For issues, questions, or suggestions, please:

📋 Open an issue on GitHub
💬 Start a discussion on GitHub Discussions
📖 Check the examples directory
📚 Read the API documentation

🚀 Roadmap

Completed Features ✅

[x] ~~CLI tool for command-line conversions~~ ✅ COMPLETED v1.1.0
[x] ~~Add watermark support for PDFs~~ ✅ COMPLETED v1.1.0
[x] ~~Support for charts and graphs in presentations~~ ✅ COMPLETED v1.2.0
[x] ~~Advanced theming engine (25+ themes)~~ ✅ COMPLETED v1.3.0
[x] ~~Implement Word document (.docx) generation~~ ✅ COMPLETED v1.4.0
[x] ~~REST API Server with Docker support~~ ✅ COMPLETED v1.5.0
[x] ~~Cloud storage integration (S3, Azure Blob Storage)~~ ✅ COMPLETED v1.6.0
[x] ~~ML-based layout detection~~ ✅ COMPLETED v1.7.0
[x] ~~Enhanced PPTX with structured content (tables, lists)~~ ✅ COMPLETED v1.8.0

Planned Features 🔮

[ ] Add support for Excel/CSV export
[ ] Google Drive cloud storage integration
[ ] Browser-based version
[ ] Template marketplace
[ ] Multi-language support

📦 Version History

v1.8.1 (Current) - Maintenance Release

Dependency updates and compatibility fixes

Updated all dependencies to latest versions
Fixed Puppeteer v24 compatibility (headless mode, buffer handling)
Updated jsdom to v27, pptxgenjs to v4, sharp to v0.34
Zero security vulnerabilities
All tests passing

v1.8.0 - PPTX Enhancement Release

Major improvements to HTML to PowerPoint conversion

Enhanced structured content extraction (tables, lists)
Native PPTX table rendering
Improved bullet point and numbered list handling
Fixed critical bugs (NodeFilter, Node types, section extraction)
Removed Puppeteer from professional mode (4x performance boost)
Better content layout with dynamic Y-positioning

v1.7.0 - ML Layout Detection

Intelligent content analysis (11 content types)
Layout pattern detection (7 patterns)
Importance scoring algorithm
Smart section grouping and page breaking
Keyword extraction and sentiment analysis

v1.6.0 - Cloud Storage Integration

AWS S3 and Azure Blob Storage support
Cloud URL parsing and automatic uploads
Unified cloud storage manager

v1.5.0 - REST API Server

Express.js REST API with job management
OpenAPI/Swagger documentation
Docker containerization

v1.4.0 - Word Document Support

HTML to DOCX conversion
Document structure preservation

v1.3.0 - Advanced Theming Engine

25+ professional theme presets
Custom theme builder

v1.2.0 - Chart Generation

Auto chart generation from tables
Multiple chart types

v1.1.0 - CLI & Watermarks

Command-line interface
PDF watermark support

v1.0.0 - Initial Release

HTML to PDF and PPTX conversion
Basic and professional modes

🌍 Community

Join our community:

🐦 Twitter: @rakesh8116
💬 Discord: Join our server
📱 Telegram: FlexDoc Community