### Quick Start Installation and Conversion

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/PROJECT_SUMMARY.md

Provides the essential commands to install the library and perform an initial HTML to PPTX conversion using the CLI.

```bash
cd /home/ubuntu/html2pptx-library
npm install
./bin/html2pptx examples/check.html output.pptx
```

--------------------------------

### Installation from Source

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/docs/installation.md

Install html2pptx directly from its source repository. This involves cloning the repository, installing dependencies, and linking the package locally, which is useful for development or contributing to the project.

```bash
git clone https://github.com/jules-dot-ai/html2pptx.git
cd html2pptx
npm install
npm link
```

--------------------------------

### Install HTML2PPTX Library

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/QUICKSTART.md

Install the necessary dependencies for the html2pptx library. Navigate to the project directory and run npm install.

```bash
cd /home/ubuntu/html2pptx-library
npm install
```

--------------------------------

### Install and Convert HTML to PPTX

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/PROJECT_SUMMARY.md

Install project dependencies and convert an HTML file to a PPTX presentation using the command-line interface.

```bash
# Install dependencies (already done)
npm install

# Convert any HTML file
./bin/html2pptx your-file.html your-presentation.pptx

# Run tests
npm test
```

--------------------------------

### Install HTML2PPTX from Source

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/README.md

Installs the html2pptx package directly from its source repository. This involves cloning the repository, installing dependencies, and linking the CLI globally.

```bash
git clone <repository-url>
cd html2pptx-library
npm install
npm link  # Makes the CLI available globally
```

--------------------------------

### CLI Conversion Examples

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/docs/usage.md

Demonstrates converting a simple HTML file and a file with a complex layout using the CLI. These examples show practical application of the basic usage.

```bash
# Convert a simple HTML file
html2pptx examples/simple.html my-presentation.pptx
```

```bash
# Convert a file with a complex layout
html2pptx examples/grid_layout.html grid-presentation.pptx
```

--------------------------------

### HTML2PPTX CLI Usage Examples

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/PROJECT_SUMMARY.md

Demonstrates common command-line interface commands for converting HTML to PPTX, including help and version checks.

```bash
html2pptx input.html output.pptx
html2pptx --help
html2pptx --version
```

--------------------------------

### Global Installation using npm

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/docs/installation.md

Install html2pptx globally for command-line interface (CLI) usage. This makes the html2pptx command available system-wide.

```bash
npm install -g html2pptx
```

--------------------------------

### Convert Example HTML Files

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/QUICKSTART.md

Convert specific example HTML files using the CLI tool. This includes converting simple text boxes and complex layouts with diagrams. Run 'npm test' to execute all tests.

```bash
# Convert simple text boxes
./bin/html2pptx examples/"5 Text Boxes 16_9.html" output1.pptx

# Convert complex layout with diagrams
./bin/html2pptx examples/check.html output2.pptx

# Run all tests
npm test
```

--------------------------------

### Local Installation using npm

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/docs/installation.md

Install html2pptx locally within your project to use it as a library. This is the recommended approach for integrating html2pptx into your application's dependencies.

```bash
npm install html2pptx
```

--------------------------------

### Simple Text Box Example

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/README.md

Demonstrates creating a basic text box with styling using HTML and CSS. This example shows how to apply borders, padding, font size, and background color to a div element.

```html
<!DOCTYPE html>
<html>
<head>
    <style>
        .container {
            width: 1280px;
            height: 720px;
        }
        .text-box {
            border: 2px solid #3498db;
            padding: 20px;
            font-size: 24px;
            background: #f8f9fa;
        }
    </style>
</head>
<body>
    <div class="container">
        <div class="text-box">Hello World!</div>
    </div>
</body>
</html>
```

--------------------------------

### Show HTML2PPTX CLI Version

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/README.md

Displays the currently installed version of the html2pptx command-line tool.

```bash
html2pptx --version
```

--------------------------------

### Project Directory Structure

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/PROJECT_SUMMARY.md

Outlines the organizational structure of the html2pptx-library project, including directories for binaries, libraries, examples, and tests.

```bash
html2pptx-library/
├── bin/
│   └── html2pptx              # Executable CLI tool
├── lib/
│   └── html2pptx.js          # Main conversion library (600+ lines)
├── examples/
│   ├── 5 Text Boxes 16_9.html # Simple example
│   └── check.html            # Complex example
├── test/
│   ├── test.js               # Test suite
│   └── output/               # Generated PPTX files
│       ├── test1-textboxes.pptx
│       ├── test2-complex.pptx
│       ├── cli-test1.pptx
│       └── cli-test2.pptx
├── .gitignore                # Git ignore file
├── package.json              # NPM package configuration
├── package-lock.json         # Dependency lock file
├── README.md                 # Main documentation
├── QUICKSTART.md            # Quick start guide
└── PROJECT_SUMMARY.md       # This file
```

--------------------------------

### Absolute Positioning Example

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/README.md

Illustrates using absolute positioning in HTML and CSS to place elements precisely on a slide. This example positions a title element at specific coordinates within a relative container.

```html
<!DOCTYPE html>
<html>
<head>
    <style>
        .slide {
            width: 1280px;
            height: 720px;
            position: relative;
        }
        .title {
            position: absolute;
            top: 50px;
            left: 100px;
            font-size: 36px;
            color: #2c3e50;
            font-weight: bold;
        }
    </style>
</head>
<body>
    <div class="slide">
        <div class="title">My Presentation</div>
    </div>
</body>
</html>
```

--------------------------------

### Basic HTML to PPTX Conversion (CLI)

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/QUICKSTART.md

Perform a basic conversion of an HTML slide file to a PowerPoint presentation using the command line. Supports full paths and provides help/version information.

```bash
# Basic conversion
html2pptx slide.html presentation.pptx

# With full paths
html2pptx /path/to/input.html /path/to/output.pptx

# Get help
html2pptx --help

# Check version
html2pptx --version
```

--------------------------------

### Basic CLI Conversion

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/docs/usage.md

Use the command-line interface to quickly convert an HTML file to a PPTX file. Specify the input HTML file and the desired output PPTX file name.

```bash
html2pptx <input.html> <output.pptx>
```

--------------------------------

### Convert HTML to PPTX with Full Paths via CLI

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/README.md

Command-line usage demonstrating the conversion of an HTML file to a PPTX file using absolute or full paths for both input and output.

```bash
html2pptx /path/to/input.html /path/to/output.pptx
```

--------------------------------

### Show HTML2PPTX CLI Help

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/README.md

Displays the help message for the html2pptx command-line tool, outlining available options and usage instructions.

```bash
html2pptx --help
```

--------------------------------

### Convert HTML to PPTX using CLI

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/QUICKSTART.md

Use the command-line interface to convert an HTML file to a PowerPoint presentation. This can be done directly or after linking the package globally.

```bash
# Using the CLI tool directly
./bin/html2pptx input.html output.pptx

# Or if installed globally
npm link
html2pptx input.html output.pptx
```

--------------------------------

### Convert HTML to PPTX via CLI

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/README.md

Basic command-line usage for converting a single HTML file to a PowerPoint presentation. Specify input and output file paths.

```bash
html2pptx input.html output.pptx
```

--------------------------------

### Programmatic Conversion (Advanced)

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/docs/usage.md

Instantiate the `HTML2PPTX` class for advanced control over conversion settings, such as slide dimensions. This allows for more customized presentations.

```javascript
const { HTML2PPTX } = require('html2pptx');

const converter = new HTML2PPTX({
    slideWidth: 12,
    slideHeight: 6.75,
});

converter.convert('input.html', 'output.pptx')
    .then(result => console.log('Success!', result));
```

--------------------------------

### Programmatic HTML to PPTX Conversion with Custom Options

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/README.md

Shows advanced programmatic usage of the html2pptx library, initializing an `HTML2PPTX` converter instance with custom options like slide dimensions and background color.

```javascript
const converter = new HTML2PPTX({
    slideWidth: 10,      // inches
    slideHeight: 5.625,  // inches (16:9 ratio)
    background: { color: 'FFFFFF' }
});

converter.convert('input.html', 'output.pptx')
    .then(result => console.log('Converted!', result))
    .catch(error => console.error('Error:', error));
```

--------------------------------

### Run html2pptx with Debug Mode

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/README.md

To troubleshoot conversion errors, run the html2pptx command with the DEBUG=1 environment variable. This provides more detailed output to help identify issues.

```bash
DEBUG=1 html2pptx input.html output.pptx
```

--------------------------------

### Integrate PPTX Post-Processor

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/CORRUPTION_FIXES.md

Shows how to import and use the 'fixPPTX' function from the custom module within the main conversion process.

```javascript
const { fixPPTX } = require('./pptx-fixer');

// In html2pptx.js convert() method:
await this.pptx.writeFile({ fileName: outputPath });

// Post-process to fix corruption
await fixPPTX(outputPath);
```

--------------------------------

### HTML2PPTX Constructor

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/docs/api-reference.md

Creates a new instance of the HTML2PPTX converter with customizable options.

```APIDOC
## `new HTML2PPTX(options)`

### Description
Creates a new instance of the `HTML2PPTX` converter.

### Parameters
#### Query Parameters
- **`options`** (object, optional): An options object.

### Options
- **`slideWidth`** (number): The width of the PowerPoint slides in inches. Default: `10`.
- **`slideHeight`** (number): The height of the PowerPoint slides in inches. Default: `5.625`.
- **`htmlWidth`** (number): The width of the HTML container in pixels, used for scaling. Default: `1280`.
- **`htmlHeight`** (number): The height of the HTML container in pixels, used for scaling. Default: `720`.
```

--------------------------------

### Simple HTML to PPTX Conversion (Programmatic API)

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/QUICKSTART.md

Convert an HTML file to a PowerPoint presentation using the programmatic API in JavaScript. Requires importing the convertHTML2PPTX function.

```javascript
const { convertHTML2PPTX } = require('./lib/html2pptx');

// Simple conversion
await convertHTML2PPTX('input.html', 'output.pptx');
```

--------------------------------

### HTML2PPTX Advanced Conversion with Custom Options

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/QUICKSTART.md

Instantiate the HTML2PPTX class with custom options for slide dimensions and background color, then use the convert method. Requires importing the HTML2PPTX class.

```javascript
const { HTML2PPTX } = require('./lib/html2pptx');

const converter = new HTML2PPTX({
    slideWidth: 10,      // inches
    slideHeight: 5.625,  // inches (16:9 ratio)
    background: { color: 'FFFFFF' }
});

await converter.convert('input.html', 'output.pptx');
```

--------------------------------

### Run HTML2PPTX Tests

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/LAYOUT_FIXES.md

This bash script shows the output of the test suite after applying layout fixes, indicating that all tests passed successfully.

```bash
$ npm test

🧪 Running HTML2PPTX Tests

Running: Test 1: Simple Text Boxes (5 Text Boxes 16_9.html)
  ✅ PASSED (36ms, 29KB)

Running: Test 2: Complex Layout (check.html)
  ✅ PASSED (18ms, 30KB)

==================================================
Test Results: 2 passed, 0 failed
==================================================

✅ All tests passed!
```

--------------------------------

### Batch HTML to PPTX Conversion

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/QUICKSTART.md

Convert multiple HTML files to PowerPoint presentations sequentially using a loop and the convertHTML2PPTX function. Logs the conversion progress for each file.

```javascript
const files = ['slide1.html', 'slide2.html', 'slide3.html'];

for (const file of files) {
    const output = file.replace('.html', '.pptx');
    await convertHTML2PPTX(file, output);
    console.log(`Converted: ${file} → ${output}`);
}
```

--------------------------------

### Programmatic Conversion (Simple)

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/docs/usage.md

Use the `convertHTML2PPTX` function from the library for straightforward HTML to PPTX conversion in Node.js. Handles success and error logging.

```javascript
const { convertHTML2PPTX } = require('html2pptx');

convertHTML2PPTX('input.html', 'output.pptx')
    .then(result => {
        console.log('Conversion successful!', result);
    })
    .catch(error => {
        console.error('An error occurred:', error);
    });
```

--------------------------------

### After Fixes: Text Box Layout

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/IMPROVEMENTS.md

Demonstrates the corrected rendering of text boxes after applying library fixes, showing accurate width, unique border colors, and proper spacing.

```text
Text Box 1: "Text Box 1"
  Position: (0.56", 0.56")
  Size: 8.89" × 0.68"
  Border: #E74C3C (Red - CORRECT ✓)

Text Box 2: "Text Box 2"
  Position: (0.56", 1.51")
  Size: 8.89" × 0.68"
  Border: #3498DB (Blue - CORRECT ✓)

Text Box 3: "Text Box 3"
  Position: (0.56", 2.47")
  Size: 8.89" × 0.68"
  Border: #2ECC71 (Green - CORRECT ✓)

Text Box 4: "Text Box 4"
  Position: (0.56", 3.43")
  Size: 8.89" × 0.68"
  Border: #F39C12 (Orange - CORRECT ✓)

Text Box 5: "Text Box 5"
  Position: (0.56", 4.39")
  Size: 8.89" × 0.68"
  Border: #9B59B6 (Purple - CORRECT ✓)
```

--------------------------------

### converter.convert

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/docs/api-reference.md

Converts an HTML file using the settings from an HTML2PPTX instance.

```APIDOC
## `converter.convert(inputPath, outputPath)`

### Description
Converts an HTML file using the settings from the `HTML2PPTX` instance.

### Parameters
#### Path Parameters
- **`inputPath`** (string): The path to the input HTML file.
- **`outputPath`** (string): The path for the output PPTX file.
```

--------------------------------

### Calculate Flexbox Item Positions with Gap and Padding

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/IMPROVEMENTS.md

This algorithm outlines the steps to calculate the position and size of flex items within a container, considering flex-direction, gap between items, and container padding. It supports equal distribution when flex: 1 is applied.

```plaintext
For flex-direction: column:
1. Calculate available height = containerHeight - paddingTop - paddingBottom
2. Calculate total gaps = (totalItems - 1) × gap
3. Calculate item height = (availableHeight - totalGaps) / totalItems (if flex: 1)
4. Calculate Y position = paddingTop + (index × (itemHeight + gap))
```

--------------------------------

### Console Output of PPTX Fixer

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/CORRUPTION_FIXES.md

Shows the expected console messages during the PPTX conversion and post-processing, indicating successful fixing and backup creation.

```text
[HTML2PPTX] Post-processing PPTX to fix corruption issues...
[PPTX Fixer] Processing: output.pptx
[PPTX Fixer] Applied 37 fixes, backup saved to output.pptx.backup
[HTML2PPTX] PPTX file fixed successfully
```

--------------------------------

### Python-pptx Output Verification

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/FLEXBOX_FIX.md

This output shows the expected structure and number of shapes after a successful conversion, verifying that all elements are present and correctly positioned.

```text
Number of shapes: 5
  Shape 1: Text Box 1 (top = 285750 EMU)
  Shape 2: Text Box 2 (top = 1228725 EMU)
  Shape 3: Text Box 3 (top = 2171700 EMU)
  Shape 4: Text Box 4 (top = 3114675 EMU)
  Shape 5: Text Box 5 (top = 4057650 EMU)
```

--------------------------------

### Automatic PPTX Fixer Usage

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/CORRUPTION_FIXES.md

Demonstrates the simple API call for converting HTML to PPTX, highlighting that the post-processing fixes are applied automatically.

```javascript
const { convertHTML2PPTX } = require('./lib/html2pptx.js');

// Automatically applies fixes
await convertHTML2PPTX('input.html', 'output.pptx');
```

--------------------------------

### Before Fixes: Text Box Layout

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/IMPROVEMENTS.md

Illustrates the incorrect rendering of text boxes before the library fixes were applied, showing issues with width, border color, and spacing.

```text
Text Box 1: "Text Box 1"
  Position: (0.50", 0.50")
  Size: 5.00" × 0.83"
  Border: #3498DB (Blue - WRONG, should be Red)

Text Box 2: "Text Box 2"
  Position: (0.50", 1.63")
  Size: 5.00" × 0.83"
  Border: #3498DB (Blue - CORRECT)

Text Box 3: "Text Box 3"
  Position: (0.50", 2.75")
  Size: 5.00" × 0.83"
  Border: #3498DB (Blue - WRONG, should be Green)

... (All had same blue border)
```

--------------------------------

### XML Namespaces in OpenXML

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/CORRUPTION_FIXES.md

Lists common XML namespaces used in OpenXML documents for presentations.

```xml
xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"
xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"
xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
```

--------------------------------

### HTML Structure and CSS Styling

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/examples/5 Text Boxes 16_9.html

This snippet contains the HTML structure for a container and five text boxes, along with CSS rules to style them. It sets up a 16:9 aspect ratio container and styles individual text boxes with unique border colors.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>5 Text Boxes - 16:9</title>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body { display: flex; justify-content: center; align-items: center; min-height: 100vh; background: #f0f0f0; padding: 20px; }
        .container { width: 100%; max-width: 1280px; aspect-ratio: 16 / 9; background: white; padding: 40px; box-shadow: 0 4px 20px rgba(0,0,0,0.1); display: flex; flex-direction: column; gap: 20px; }
        .text-box { flex: 1; border: 2px solid #3498db; border-radius: 8px; padding: 20px; background: #f8f9fa; display: flex; align-items: center; justify-content: center; font-size: 24px; font-family: Arial, sans-serif; color: #2c3e50; }
        .text-box:nth-child(1) { border-color: #e74c3c; }
        .text-box:nth-child(2) { border-color: #3498db; }
        .text-box:nth-child(3) { border-color: #2ecc71; }
        .text-box:nth-child(4) { border-color: #f39c12; }
        .text-box:nth-child(5) { border-color: #9b59b6; }
    </style>
</head>
<body>
    <div class="container">
        <div class="text-box">Text Box 1</div>
        <div class="text-box">Text Box 2</div>
        <div class="text-box">Text Box 3</div>
        <div class="text-box">Text Box 4</div>
        <div class="text-box">Text Box 5</div>
    </div>
</body>
</html>
```

--------------------------------

### HTML Structure for Flex Column Layout

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/FLEXBOX_FIX.md

This HTML structure demonstrates a typical flex column layout with a gap, which was problematic for the previous conversion logic.

```html
<div class="container" style="display: flex; flex-direction: column; gap: 20px;">
    <div class="text-box">Text Box 1</div>
    <div class="text-box">Text Box 2</div>
    <div class="text-box">Text Box 3</div>
    <div class="text-box">Text Box 4</div>
    <div class="text-box">Text Box 5</div>
</div>
```

--------------------------------

### convertHTML2PPTX

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/docs/api-reference.md

A convenience function for quick HTML to PPTX conversions.

```APIDOC
## `convertHTML2PPTX(inputPath, outputPath, options)`

### Description
A convenience function for quick conversions.

### Parameters
#### Path Parameters
- **`inputPath`** (string): The path to the input HTML file.
- **`outputPath`** (string): The path where the output PPTX file will be saved.
#### Query Parameters
- **`options`** (object, optional): An options object to customize the conversion. See below for details.
```

--------------------------------

### Test Results Summary

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/PROJECT_SUMMARY.md

Displays the outcome of automated tests, indicating passed conversions and their performance metrics.

```bash
✅ Test 1: Simple Text Boxes - PASSED (24ms, 47KB)
✅ Test 2: Complex Layout - PASSED (13ms, 81KB)
✅ CLI Test 1 - PASSED (20ms, 48KB)
✅ CLI Test 2 - PASSED (30ms, 81KB)
```

--------------------------------

### HTML Structure for Grid Items

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/examples/grid_layout.html

Provides the HTML markup for individual items that will be placed within the CSS grid container. Each item is a simple div with a class 'item'.

```html
Item 1

Item 2

Item 3

Item 4

Item 5

Item 6
```

--------------------------------

### After Fix: Properly Stacked Text Elements

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/POSITIONING_FIX.md

This output log demonstrates the corrected positioning after the fix. Text elements are now properly stacked vertically with correct horizontal centering, showing distinct x and y coordinates.

```text
[POS] <h1> "The CAP Theorem" -> x:64.00, y:311.40
[POS] <h2> "Navigating Trade-offs..." -> x:64.00, y:334.60
[POS] <p> "Consistency, Availability..." -> x:64.00, y:377.80
[POS] <p> "Manus AI" -> x:64.00, y:443.70
[POS] <p> "October 2025" -> x:64.00, y:477.70
```

--------------------------------

### Delegate to Recursive Position Calculator

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/POSITIONING_FIX.md

This snippet shows the new approach in `calculateElementPosition` which delegates the actual position calculation to a new recursive method. This is part of the refactored positioning logic.

```javascript
const position = this.calculateAbsolutePosition($, $elem, parentStyle, w, h);
x = position.x;
y = position.y;
```

--------------------------------

### Dependency for ZIP Manipulation

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/CORRUPTION_FIXES.md

Specifies the 'adm-zip' package as a dependency for handling ZIP archives, used in the PPTX post-processor.

```json
{
  "adm-zip": "^0.5.10"  // For ZIP manipulation
}
```

--------------------------------

### CSS Grid Layout Container

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/examples/grid_layout.html

Defines a container with a fixed width and height, using CSS Grid to create three equal columns with a 20px gap. Includes padding for internal spacing.

```css
.container { width: 1280px; height: 720px; display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 20px; padding: 20px; }
```

--------------------------------

### Before Fix: Overlapping Text Elements

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/POSITIONING_FIX.md

This output log shows the state of text elements before the fix. All elements are positioned at the origin (0.00, 0.00), indicating severe overlapping and incorrect positioning.

```text
[POS] <h1> "The CAP Theorem" -> x:0.00, y:0.00
[POS] <h2> "Navigating Trade-offs..." -> x:0.00, y:0.00
[POS] <p> "Consistency, Availability..." -> x:0.00, y:0.00
[POS] <p> "Manus AI" -> x:0.00, y:0.00
[POS] <p> "October 2025" -> x:0.00, y:0.00
```

--------------------------------

### Flexbox Column Layout Fix Implementation

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/FLEXBOX_FIX.md

This code snippet demonstrates the solution implemented in html2pptx. It detects flexbox column layouts and calculates the Y position of elements based on their sibling order, height, and gap spacing, ensuring correct rendering.

```javascript
if (parentStyle.display === 'flex' && parentStyle['flex-direction'] === 'column') {
    // FLEX COLUMN FIX: Calculate position based on sibling order
    const siblings = parent.children();
    const index = siblings.index($elem[0]);
    
    // Get gap value
    const gap = this.parsePixelValue(parentStyle.gap || '0');
    
    // Calculate Y position based on previous siblings
    let flexY = 0;
    for (let i = 0; i < index; i++) {
        const sibling = siblings.eq(i);
        const siblingStyle = this.getComputedStyle($, sibling[0]);
        
        // Get sibling height (with flex: 1 support)
        let siblingHeight = /* calculation logic */;
        
        flexY += siblingHeight + gap;
    }
    
    accumulatedY += flexY;
    
    // Add parent padding
    if (parentStyle.padding) {
        accumulatedY += this.parsePixelValue(parentStyle.padding);
    }
}
```

--------------------------------

### Git Commit for Layout Fixes

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/LAYOUT_FIXES.md

This commit details the changes made to fix dimension calculations for flexbox layouts in HTML2PPTX. It highlights improvements in height and width calculations, and the reorganization of the layout logic.

```git
commit 787e170
Author: HTML2PPTX Converter
Date:   [Current Date]

    Fix: Properly calculate dimensions for flexbox layouts
    
    - Fixed height calculation for elements with flex: 1 in column layouts
    - Elements now properly inherit their height from available space
    - Added proper width calculation for flex items accounting for padding
    - Reorganized dimension calculation logic to handle flex layouts first
    - All tests pass with improved layout accuracy
```

--------------------------------

### Debugged Element Positions in Flexbox

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/FLEXBOX_FIX.md

Illustrates the incorrect Y coordinate calculation for multiple elements in a flexbox column layout before the fix. All elements share the same Y value, causing them to stack.

```text
Text Box 1: { x: 1, y: 2.71875, w: 8, h: 0.1875 }
Text Box 2: { x: 1, y: 2.71875, w: 8, h: 0.1875 }
Text Box 3: { x: 1, y: 2.71875, w: 8, h: 0.1875 }
Text Box 4: { x: 1, y: 2.71875, w: 8, h: 0.1875 }
Text Box 5: { x: 1, y: 2.71875, w: 8, h: 0.1875 }
```

--------------------------------

### Apply Flex Container Centering

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/POSITIONING_FIX.md

This snippet shows how vertical centering is applied for flex containers with `flex-direction: column` and `justify-content: center`. This addresses centering issues within flexbox layouts.

```javascript
// Apply flex container centering
if (grandParentStyle['justify-content'] === 'center' && grandParentStyle['flex-direction'] === 'column') {
    const verticalOffset = (grandParentHeight - totalContentHeight) / 2;
    y += verticalOffset;
}
```

--------------------------------

### Fix Small Dimensions in XML

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/CORRUPTION_FIXES.md

Replaces XML attributes with values less than 10000 EMUs with 'cy="10000"' to ensure minimum dimensions.

```javascript
// Enforce minimum height of 10,000 EMUs
fixed = fixed.replace(
    /cy="(\d{1,4})"/g,
    (match, value) => {
        const num = parseInt(value);
        if (num > 0 && num < 10000) {
            return 'cy="10000"';
        }
        return match;
    }
);
```

--------------------------------

### Git Commit for Flexbox Layout Fix

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/FIX_SUMMARY.md

This commit details the fix for properly calculating dimensions in flexbox layouts, specifically addressing height inheritance and width calculation for flex items. It ensures improved layout accuracy in the HTML2PPTX converter.

```bash
commit 787e170
Author: HTML2PPTX Converter
Date:   October 15, 2025

    Fix: Properly calculate dimensions for flexbox layouts
    
    - Fixed height calculation for elements with flex: 1 in column layouts
    - Elements now properly inherit their height from available space
    - Added proper width calculation for flex items accounting for padding
    - Reorganized dimension calculation logic to handle flex layouts first
    - All tests pass with improved layout accuracy
    
    This fixes the issue where text boxes were too thin vertically when
    using flexbox with flex: 1. The boxes now correctly divide the
    available vertical space as specified in the HTML/CSS.

 lib/html2pptx.js | 118 +++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 76 insertions(+), 42 deletions(-)

```

--------------------------------

### Git Commit for PPTX Corruption Fixes

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/CORRUPTION_FIXES.md

This commit message outlines the root causes of PPTX corruption issues and the solution implemented using the pptx-fixer.js module for automatic post-processing.

```bash
commit ffef1c5
Author: HTML2PPTX Development
Date: [Current Date]

Fix PPTX corruption issues by post-processing generated files

ROOT CAUSES FIXED:
1. Empty name attributes in p:cNvPr elements
2. Empty a:ln elements
3. Zero dimensions in group shapes
4. Conflicting autofit settings
5. Very small dimension values
6. Invalid negative charset values

SOLUTION:
- Created pptx-fixer.js module
- Automatic post-processing
- Generic regex-based fixes
- ZIP manipulation with adm-zip

TESTING:
- 3 HTML files tested
- All pass validation
- 37-133 fixes per file
```

--------------------------------

### CSS Grid Item Styling

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/examples/grid_layout.html

Styles individual items within the grid container, applying a background color, border, padding, and text alignment for a consistent appearance.

```css
.item { background-color: #f0f0f0; border: 2px solid #333; padding: 20px; text-align: center; font-size: 24px; }
```

--------------------------------

### Commit Message: Flexbox Column Layout Fix

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/FLEXBOX_FIX.md

This commit message summarizes the root cause, solution, and verified test cases for the flexbox column layout positioning issue.

```text
Fix: Properly handle flexbox column layouts with gaps

ROOT CAUSE: The calculateElementPosition method was not accounting for
flexbox layouts with flex-direction: column and gap properties. This
caused all sibling elements to be positioned at the same Y coordinate,
resulting in elements stacking on top of each other.

SOLUTION: Added flex column layout detection and calculation logic:
- Detects when parent uses flex with column direction
- Calculates Y position based on sibling order
- Accounts for gap values between flex items
- Handles both fixed heights and flex: 1 layouts
- Includes parent padding in calculations

This ensures each element in a flex column gets a unique Y position
based on its position in the layout hierarchy.

Test cases verified:
- 5 Text Boxes layout: All 5 boxes now render with proper spacing
- CAP Theorem slide: All 5 text elements render correctly
```

--------------------------------

### Apply Text-Align Centering

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/POSITIONING_FIX.md

This code applies horizontal centering for text elements based on the `text-align` style property, considering both the element's and its parent's styles. This is part of the smart centering logic.

```javascript
// Apply text-align centering within parent
if (currentStyle['text-align'] === 'center' || parentStyle['text-align'] === 'center') {
    x = x - padding + (availableWidth - elemWidth) / 2;
}
```

--------------------------------

### Calculate Height for Flex Items

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/FIX_SUMMARY.md

This JavaScript code snippet detects flexbox layouts and correctly calculates the height for flex items with 'flex: 1' style. It accounts for parent container height, padding, and gaps between sibling elements. Use this when dealing with vertical flex layouts where elements should equally share available space.

```javascript
// NEW: Detect flex layouts and calculate dimensions properly
if (parentStyle.display === 'flex') {
    if (parentStyle['flex-direction'] === 'column') {
        // Calculate height for flex: 1 items
        if (style.flex === '1' || style.flex === '1 1 0%' || style.flex) {
            const flexCount = siblings.filter(...).length;
            const parentHeight = this.parsePixelValue(parentStyle.height || '720px');
            const parentPadding = this.parsePixelValue(parentStyle.padding || '0') * 2;
            const totalGaps = gap * (siblings.length - 1);
            const availableHeight = parentHeight - parentPadding - totalGaps;
            
            h = availableHeight / flexCount; // ✅ CORRECT HEIGHT
        }
    }
}
```

--------------------------------

### Corrected Element Positions After Fix

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/FLEXBOX_FIX.md

Shows the corrected Y coordinates for elements after applying the flexbox layout fix. Each element now has a unique Y position, resolving the overlap issue.

```text
Text Box 1: { x: 1, y: 0.3125,   w: 8, h: 0.1875 }  ✅
Text Box 2: { x: 1, y: 1.34375,  w: 8, h: 0.1875 }  ✅
Text Box 3: { x: 1, y: 2.375,    w: 8, h: 0.1875 }  ✅
Text Box 4: { x: 1, y: 3.40625,  w: 8, h: 0.1875 }  ✅
Text Box 5: { x: 1, y: 4.4375,   w: 8, h: 0.1875 }  ✅
```

--------------------------------

### Calculate Y Offset from Previous Siblings

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/POSITIONING_FIX.md

This code calculates the vertical offset by iterating through previous siblings and accumulating their heights, including margins and gaps. This is a key part of the new positioning algorithm for tracking document flow.

```javascript
// Calculate Y offset from previous siblings
for (let i = 0; i < index; i++) {
    const sibling = siblings.eq(i);
    // Calculate and add sibling height
    y += siblingHeight;
    // Add margins and gaps
}
```

--------------------------------

### Parse Border Radius for Rounded Rectangles

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/IMPROVEMENTS.md

This JavaScript code snippet demonstrates how to parse the 'border-radius' CSS property. If a valid radius is found, it sets the shape to a rounded rectangle and converts the radius value from pixels to inches for presentation.

```javascript
if (style['border-radius']) {
    const borderRadius = this.parsePosition(style['border-radius']);
    if (borderRadius > 0) {
        options.shape = this.pptx.ShapeType.roundRect;
        options.rectRadius = borderRadius / 72; // Convert px to inches
    }
}
```

--------------------------------

### Remove Conflicting Autofit Settings

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/CORRUPTION_FIXES.md

Resolves conflicts in text body autofit settings by removing the 'spAutoFit' element when 'normAutofit' is present. This ensures only one autofit behavior is applied.

```javascript
fixed = fixed.replace(
    /(<a:bodyPr[^>]*>)(.*?)<a:normAutofit\s*\/>(.*?)<a:spAutoFit\s*\/>/gi,
    (match, opening, before, after) => 
        `${opening}${before}<a:normAutofit/>${after}`
);
```

--------------------------------

### Tailwind CSS Utility Class Mapping

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/POSITIONING_FIX.md

This JavaScript function maps common Tailwind CSS utility class names to their corresponding CSS properties. This enables the library to parse and apply styles from Tailwind CSS classes used in HTML.

```javascript
getTailwindStyle(className) {
    const tailwindMap = {
        'flex': { 'display': 'flex' },
        'flex-col': { 'flex-direction': 'column' },
        'items-center': { 'align-items': 'center' },
        'justify-center': { 'justify-content': 'center' },
        'text-center': { 'text-align': 'center' },
        // ... more classes
    };
    return tailwindMap[className] || null;
}
```

--------------------------------

### Remove Empty Line Elements

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/CORRUPTION_FIXES.md

Cleans up invalid XML by removing empty line elements (<a:ln></a:ln> or <a:ln/>). This ensures that line properties are either correctly defined or omitted.

```javascript
fixed = fixed.replace(/<a:ln\s*><\/a:ln>/g, '');
fixed = fixed.replace(/<a:ln\s*\/>/g, '');
```

--------------------------------

### Fix Incorrect Height for Flex Items

Source: https://github.com/abdelkrimkr/html2pptx/blob/master/LAYOUT_FIXES.md

This snippet demonstrates the corrected logic for calculating the height of flex items with `flex: 1` in a column flex container. It ensures elements properly divide available vertical space, accounting for parent padding and gaps.

```javascript
// Before: Height fallback was too small
if (style.height) {
    h = this.parsePixelValue(style.height);
} else {
    h = lineHeight * estimatedLines; // TOO SMALL for flex items!
}

// After: Proper flex item height calculation
if (style.flex === '1' || style.flex === '1 1 0%' || style.flex) {
    const flexCount = siblings.filter((j, el) => {
        const s = this.getComputedStyle($, el);
        return s.flex === '1' || s.flex === '1 1 0%' || s.flex;
    }).length;
    
    const parentHeight = this.parsePixelValue(parentStyle.height || parentStyle['min-height'] || '720px');
    const parentPadding = this.parsePixelValue(parentStyle.padding || '0') * 2;
    const totalGaps = gap * (siblings.length - 1);
    const availableHeight = parentHeight - parentPadding - totalGaps;
    
    h = availableHeight / flexCount; // CORRECT height for flex items
}
```