flexdoc/README.md

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 and clou

# FlexDoc 📄

<p align="center">
  <strong>A flexible, lightweight npm library for converting HTML to PDF, PPTX, and DOCX formats</strong>
  <br>
  <em>Professional-grade, open-source alternative to Adobe's expensive APIs</em>
</p>

<p align="center">
  <a href="#features">Features</a> •
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#api-documentation">API</a> •
  <a href="#examples">Examples</a> •
  <a href="#contributing">Contributing</a> •
  <a href="#support-this-project">Support</a>
</p>

---

## 🎉 What's New in v1.8.0

**Major PPTX Enhancements** - Production-ready HTML to PowerPoint conversion!

- ✨ **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!
- 🐛 **Critical Bug Fixes**: Fixed section extraction, NodeFilter compatibility, and slide counting
- 💪 **Structured Content**: Text, tables, and lists intelligently laid out in slides

**Performance**: 11-slide business presentation in 131ms (standard) or 32ms (professional mode)

[See full changelog →](#version-history)

---

## 🌟 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

```bash
npm install flexdoc
```

or with yarn:

```bash
yarn add flexdoc
```

## 🚀 Quick Start

### Basic Usage

```javascript
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

```typescript
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:

```javascript
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:

```bash
# Global installation
npm install -g flexdoc

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

### Commands

#### Convert to PDF

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
flexdoc batch config.json
```

**Example config.json:**
```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

```bash
flexdoc info
```

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

### CLI Examples

```bash
# 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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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:

```javascript
// 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

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

### Create a Presentation from HTML

```javascript
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:

```javascript
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:

```javascript
// 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:**
```bash
# 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

```javascript
// 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

```javascript
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:

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
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

```bash
# 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

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

### Custom Styling and Scripts

```javascript
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

```javascript
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

```javascript
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:

```bash
npm test
```

Run examples:

```bash
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

1. **Fork the repository**
2. **Create your feature branch** (`git checkout -b feature/AmazingFeature`)
3. **Commit your changes** (`git commit -m 'Add some AmazingFeature'`)
4. **Push to the branch** (`git push origin feature/AmazingFeature`)
5. **Open a Pull Request**

### Development Setup

```bash
# 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](https://github.com/rakeshwfg/flexdoc)
- 💝 **Sponsor on GitHub**: [Become a sponsor](https://github.com/sponsors/rakeshwfg)
- ☕ **Buy me a coffee**: [ko-fi.com/rakeshsingh16](https://ko-fi.com/rakeshsingh16)
- 💳 **One-time donation**: [PayPal](https://paypal.me/rakesh8116)

### 🌟 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: rakesh16@gmail.com
- 🔗 LinkedIn: [Rakesh Singh](https://www.linkedin.com/in/rakesh-singh-1ab4563/)
- 💼 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](LICENSE) file for details.

## 🙏 Acknowledgments

- [Puppeteer](https://github.com/puppeteer/puppeteer) for PDF generation
- [PptxGenJS](https://github.com/gitbrent/PptxGenJS) for PPTX creation
- [jsdom](https://github.com/jsdom/jsdom) for HTML parsing
- [html-to-text](https://github.com/html-to-text/node-html-to-text) for text extraction
- [Sharp](https://github.com/lovell/sharp) for image processing

## 📞 Support

For issues, questions, or suggestions, please:
- 📋 Open an issue on [GitHub](https://github.com/rakeshwfg/flexdoc/issues)
- 💬 Start a discussion on [GitHub Discussions](https://github.com/rakeshwfg/flexdoc/discussions)
- 📖 Check the [examples](./examples) directory
- 📚 Read the [API documentation](#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](https://x.com/rakesh8116)
- 💬 Discord: [Join our server](https://discord.gg/yourserver)
- 📱 Telegram: [FlexDoc Community](https://t.me/flexdoc)

---

<p align="center">
  <strong>Made with ❤️ by <a href="https://github.com/rakeshwfg">Rakesh Singh</a></strong>
  <br>
  <sub>Free and Open Source • Enterprise Ready • Zero Dependencies Cost</sub>
</p>

<p align="center">
  <a href="https://github.com/rakeshwfg/flexdoc/stargazers">⭐ Star us on GitHub!</a>
</p>