Update README.md

README.md

@@ -9,518 +9,406 @@ health_check:
   path: /health
 ---
 
-# HTML to PDF Converter API
+# HTML to PDF Converter API 📄
 
-A powerful API to convert HTML documents to PDF with support for page breaks, image embedding, and multiple aspect ratios.
+Convert HTML files to PDF with automatic image embedding and page break management. Perfect for generating reports, presentations, and documents from HTML.
 
-## Features
+## 🚀 Quick Start
 
-- Convert HTML files to PDF
-- Support for multiple aspect ratios (16:9, 1:1, 9:16, auto)
-- Automatic aspect ratio detection from content
-- Image embedding support
-- Page break support
-- Base64 PDF output option
+### Basic Conversion (HTML only)
 
-# HTML to PDF Conversion - Complete Implementation Guide
-
-## 🎯 Overview
-
-This guide covers the **optimized HTML to PDF conversion system** based on 2024-2025 Puppeteer best practices, implementing proper multi-page support, intelligent mode detection, and professional PDF generation.
-
----
-
-
-## 🚀 Usage Examples
-
-### Example 1: Auto-Detection (Recommended)
 ```bash
 curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \
-  -F "html_file=@document.html" \
-  -F "aspect_ratio=auto" \
-  -F "mode=single" \
+  -F "html_file=@your_file.html" \
   -o output.pdf
 ```
 
-The system will:
-- Analyze HTML structure
-- Detect page breaks and content height
-- Choose optimal aspect ratio
-- Select best generation mode
+### With Images
 
-### Example 2: Force Multi-Page Document
 ```bash
 curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \
   -F "html_file=@report.html" \
-  -F "aspect_ratio=9:16" \
-  -F "mode=multi" \
-  -o report.pdf
+  -F "images=@image1.png" \
+  -F "images=@image2.jpg" \
+  -F "images=@logo.svg" \
+  -o output.pdf
 ```
 
-### Example 3: Single-Page Infographic
-```bash
-curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \
-  -F "html_file=@infographic.html" \
-  -F "aspect_ratio=1:1" \
-  -F "mode=single" \
-  -o infographic.pdf
-```
+### Custom Aspect Ratio
 
-### Example 4: Presentation Slides
 ```bash
 curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \
   -F "html_file=@presentation.html" \
   -F "aspect_ratio=16:9" \
-  -F "mode=multi" \
+  -F "auto_detect=false" \
   -o slides.pdf
 ```
 
-### Example 5: With Images
-```bash
-curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \
-  -F "html_file=@document.html" \
-  -F "images=@logo.png" \
-  -F "images=@chart.jpg" \
-  -o document.pdf
-```
+## 📋 API Endpoints
 
----
+### `POST /convert`
 
-## 🎨 CSS Best Practices
+Convert HTML file to PDF with optional images.
 
-### Essential CSS for Multi-Page PDFs
+**Parameters:**
+- `html_file` (required): HTML file to convert
+- `images` (optional): Image files referenced in HTML (can upload multiple)
+- `aspect_ratio` (optional): `16:9`, `1:1`, or `9:16`
+- `auto_detect` (optional): Auto-detect aspect ratio from HTML (default: `true`)
 
-```css
-/* 1. Configure page size */
-@page {
-    size: A4 portrait;
-    margin: 20mm;
-}
+**Response:**
+- PDF file (application/pdf)
+- Headers include metadata: aspect ratio, image count, PDF size
 
-/* 2. Prevent unwanted breaks */
-.keep-together {
-    page-break-inside: avoid;
-    break-inside: avoid;
-}
-
-/* 3. Force page breaks */
-.new-page {
-    page-break-before: always;
-    break-before: page;
-}
-
-.page, .slide {
-    page-break-after: always;
-    break-after: page;
-}
+### `POST /convert-string`
 
-/* 4. Avoid breaking after headings */
-h1, h2, h3, h4, h5, h6 {
-    page-break-after: avoid;
-    break-after: avoid;
-}
+Convert HTML string to PDF (for HTML without external images).
 
-/* 5. Table header repetition */
-thead {
-    display: table-header-group;
-    break-inside: avoid;
-}
+**Parameters:**
+- `html_content` (required): HTML content as string
+- `aspect_ratio` (optional): `16:9`, `1:1`, or `9:16`
+- `auto_detect` (optional): Auto-detect aspect ratio (default: `true`)
 
-/* 6. Prevent table row breaks */
-tr {
-    page-break-inside: avoid;
-}
-
-/* 7. Keep images intact */
-img, figure {
-    page-break-inside: avoid;
-    break-inside: avoid;
-    max-width: 100%;
-    height: auto;
-}
+**Example:**
 
-/* 8. Ensure backgrounds print */
-* {
-    -webkit-print-color-adjust: exact !important;
-    print-color-adjust: exact !important;
-}
+```bash
+curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert-string \
+  -F "html_content=<html><body><h1>Hello World</h1></body></html>" \
+  -o output.pdf
 ```
 
-### Print-Specific Styles
-
-```css
-@media print {
-    /* Hide elements that shouldn't print */
-    .no-print {
-        display: none;
-    }
-    
-    /* Optimize for printing */
-    body {
-        font-size: 12pt;
-        line-height: 1.4;
-    }
-    
-    /* Avoid color backgrounds for text readability */
-    .text-content {
-        background: white;
-        color: black;
-    }
-}
-```
+### `GET /health`
 
----
+Health check endpoint.
 
-## 📐 Aspect Ratios Guide
+```bash
+curl https://abdallalswaiti-htmlpdfs.hf.space/health
+```
 
-### **9:16 - Portrait (Default)**
-- **Best for**: Reports, documents, invoices, contracts
-- **Format**: A4 portrait (210mm × 297mm)
-- **Use case**: Traditional business documents
+## 🎨 Features
 
-```html
-<!-- Auto-detected for standard documents -->
-<html>
-<head>
-    <meta name="orientation" content="portrait">
-</head>
-...
-```
+### ✅ Automatic Image Path Normalization
 
-### **16:9 - Landscape**
-- **Best for**: Presentations, slides, dashboards
-- **Format**: A4 landscape (297mm × 210mm)
-- **Use case**: Wide-format content
+The API automatically converts complex image paths to simple filenames:
 
+**Before:**
 ```html
-<!-- Auto-detected for presentations -->
-<html>
-<head>
-    <meta name="orientation" content="landscape">
-</head>
-<body>
-    <div class="slide">Slide 1</div>
-    <div class="slide">Slide 2</div>
-</body>
+<img src="../../../assets/images/logo.png">
+<img src="images/photo.jpg">
 ```
 
-### **1:1 - Square**
-- **Best for**: Social media, Instagram posts, certificates
-- **Format**: 210mm × 210mm
-- **Use case**: Square format content
-
+**After (automatically):**
 ```html
-<!-- Specify explicitly -->
-<html data-aspect-ratio="1:1">
-...
+<img src="logo.png">
+<img src="photo.jpg">
 ```
 
-### **Auto - Dynamic**
-- **Best for**: Infographics, posters, or any content where the exact dimensions should be preserved.
-- **Format**: The PDF will have the same dimensions as the HTML content.
-- **Use case**: When you want the PDF to be a perfect snapshot of the HTML content.
+Just upload your images with the `images` parameter, and they'll work!
 
----
+### ✅ Aspect Ratio Detection
 
-## 🎯 Mode Selection Guide
+The API automatically detects aspect ratio from:
+- HTML `<meta name="viewport">` tags
+- CSS `aspect-ratio` properties
+- Keywords like "presentation", "slide"
 
-### **Auto Mode (Recommended)**
-```javascript
-mode: "auto"
-```
-- System analyzes content
-- Detects page breaks in CSS
-- Measures content height
-- Chooses optimal mode automatically
-
-**Auto-detection logic:**
-- Finds `.page` or `.slide` classes → Multi-page
-- Content height > 2× viewport → Multi-page
-- Keywords like "infographic", "poster" → Single-page
-- Otherwise → Multi-page (safer default)
-
-### **Multi-Page Mode**
-```javascript
-mode: "multi"
-```
-- Natural page breaks respected
-- Table headers repeat
-- Content flows across pages
-- Best for documents, reports, articles
+Supported ratios:
+- **16:9** - Landscape (presentations, slides) → A4 Landscape
+- **9:16** - Portrait (reports, documents) → A4 Portrait
+- **1:1** - Square (social media posts) → 210mm × 210mm
 
-### **Single-Page Mode**
-```javascript
-mode: "single"
-```
-- Everything on one page
-- Page sized to content
-- Perfect for infographics
-- No page breaks applied
-
----
+### ✅ Automatic Page Breaks
 
-## 🔧 Advanced Configuration
+The API intelligently handles page breaks:
+- Elements with classes: `.page`, `.slide`, `section.page`
+- Top-level `<section>`, `<article>`, `<div>` elements
+- Prevents breaking inside: headings, images, tables, code blocks
 
-### Custom Page Sizes
-
-```css
-/* Custom dimensions */
-@page {
-    size: 8.5in 11in; /* Letter size */
-}
+### ✅ Color Preservation
 
-@page {
-    size: 420mm 594mm; /* A2 size */
-}
+All colors, backgrounds, and gradients are preserved in the PDF with `print-color-adjust: exact`.
 
-@page {
-    size: landscape; /* Generic landscape */
-}
-```
+## 💡 Usage Examples
 
-### Headers and Footers
+### Example 1: Simple Report
 
-```css
-@page {
-    @top-center {
-        content: "Document Title";
-    }
-    
-    @bottom-right {
-        content: counter(page) " of " counter(pages);
-    }
-}
+```bash
+curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \
+  -F "html_file=@report.html" \
+  -o report.pdf
 ```
 
-### Margins
-
-```css
-@page {
-    margin: 25mm 20mm; /* top/bottom left/right */
-}
+### Example 2: Presentation with Images
 
-@page {
-    margin-top: 30mm;
-    margin-bottom: 25mm;
-    margin-left: 20mm;
-    margin-right: 20mm;
-}
+```bash
+curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \
+  -F "html_file=@slides.html" \
+  -F "images=@chart1.png" \
+  -F "images=@chart2.png" \
+  -F "images=@logo.svg" \
+  -F "aspect_ratio=16:9" \
+  -o presentation.pdf
 ```
 
----
-
-## 🐛 Troubleshooting
-
-### Issue: Page breaks in wrong places
-**Solution**: Add `page-break-inside: avoid` to container elements
+### Example 3: Multiple Images from Directory
 
-```css
-.section {
-    page-break-inside: avoid;
-}
+```bash
+curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \
+  -F "html_file=@document.html" \
+  $(for img in images/*.{png,jpg}; do echo "-F images=@$img"; done) \
+  -o document.pdf
 ```
 
-### Issue: Table headers not repeating
-**Solution**: Ensure proper CSS on `<thead>`
+### Example 4: Python Script
 
-```css
-thead {
-    display: table-header-group;
-    break-inside: avoid;
-}
-```
-
-### Issue: Backgrounds not printing
-**Solution**: Add color-adjust property
+```python
+import requests
 
-```css
-* {
-    -webkit-print-color-adjust: exact;
-    print-color-adjust: exact;
+# Prepare files
+files = {
+    'html_file': open('report.html', 'rb'),
 }
-```
 
-### Issue: Content cut off at page edges
-**Solution**: Add appropriate margins
-
-```css
-@page {
-    margin: 20mm;
-}
+# Add images
+images = [
+    ('images', open('image1.png', 'rb')),
+    ('images', open('image2.jpg', 'rb')),
+]
 
-body {
-    padding: 0; /* Remove body padding when using @page margins */
+# Optional parameters
+data = {
+    'aspect_ratio': '9:16',
+    'auto_detect': 'false'
 }
-```
-
-### Issue: Fonts not loading
-**Solution**: Ensure fonts are embedded or use web-safe fonts
 
-```css
-@font-face {
-    font-family: 'CustomFont';
-    src: url(data:font/woff2;base64,...);
-}
+# Make request
+response = requests.post(
+    'https://abdallalswaiti-htmlpdfs.hf.space/convert',
+    files=files,
+    data=data,
+    files=files + images
+)
+
+# Save PDF
+if response.status_code == 200:
+    with open('output.pdf', 'wb') as f:
+        f.write(response.content)
+    print("PDF generated successfully!")
+else:
+    print(f"Error: {response.status_code}")
+    print(response.text)
 ```
 
----
-
-## 📊 Performance Optimization
-
-### 1. Reuse Browser Instance (for high-volume)
-Not implemented in current single-request design, but for high-volume:
+### Example 5: JavaScript/Node.js
 
 ```javascript
-// Keep one browser instance
-const browser = await puppeteer.launch();
-
-// Reuse for multiple PDFs
-for (let html of htmlList) {
-    const page = await browser.newPage();
-    await page.setContent(html);
-    await page.pdf({...});
-    await page.close();
+const FormData = require('form-data');
+const fs = require('fs');
+const fetch = require('node-fetch');
+
+async function convertToPDF() {
+    const form = new FormData();
+    
+    // Add HTML file
+    form.append('html_file', fs.createReadStream('report.html'));
+    
+    // Add images
+    form.append('images', fs.createReadStream('image1.png'));
+    form.append('images', fs.createReadStream('image2.jpg'));
+    
+    // Optional parameters
+    form.append('aspect_ratio', '9:16');
+    
+    const response = await fetch(
+        'https://abdallalswaiti-htmlpdfs.hf.space/convert',
+        {
+            method: 'POST',
+            body: form
+        }
+    );
+    
+    if (response.ok) {
+        const buffer = await response.arrayBuffer();
+        fs.writeFileSync('output.pdf', Buffer.from(buffer));
+        console.log('PDF generated successfully!');
+    } else {
+        console.error('Error:', await response.text());
+    }
 }
 
-await browser.close();
+convertToPDF();
 ```
 
-### 2. Optimize Images
-- Use compressed formats (WebP, optimized JPEG)
-- Resize to display dimensions
-- Embed as data URLs for self-contained PDFs
-
-### 3. Minimize CSS
-- Remove unused styles
-- Combine selectors
-- Use shorthand properties
+## 📝 HTML Best Practices
 
-### 4. Reduce Wait Times
-```javascript
-// Only wait for what's needed
-waitUntil: 'networkidle2' // Instead of networkidle0
-```
+### For Multi-Page Documents
 
----
+Use page classes to control page breaks:
 
-## 🎓 Real-World Examples
-
-### Invoice Template
 ```html
-<!DOCTYPE html>
-<html>
-<head>
-    <style>
-        @page { size: A4; margin: 20mm; }
-        .invoice-header { page-break-after: avoid; }
-        .invoice-items { page-break-inside: auto; }
-        thead { display: table-header-group; }
-    </style>
-</head>
-<body>
-    <div class="invoice-header">
-        <h1>INVOICE</h1>
-        <p>Date: 2024-10-17</p>
-    </div>
-    <table class="invoice-items">
-        <thead>
-            <tr><th>Item</th><th>Qty</th><th>Price</th></tr>
-        </thead>
-        <tbody>
-            <!-- Items -->
-        </tbody>
-    </table>
-</body>
-</html>
+<div class="page">
+    <h1>Page 1</h1>
+    <p>Content here...</p>
+</div>
+
+<div class="page">
+    <h1>Page 2</h1>
+    <p>More content...</p>
+</div>
 ```
 
-### Multi-Page Report
+### For Presentations (16:9)
+
 ```html
 <!DOCTYPE html>
 <html>
 <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, orientation=landscape">
     <style>
-        @page { size: A4 portrait; margin: 25mm; }
-        .page { page-break-after: always; }
-        .page:last-child { page-break-after: auto; }
-        h1 { page-break-after: avoid; }
+        .slide {
+            width: 100vw;
+            height: 100vh;
+            display: flex;
+            flex-direction: column;
+            justify-content: center;
+            align-items: center;
+        }
     </style>
 </head>
 <body>
-    <div class="page">
-        <h1>Executive Summary</h1>
-        <p>Content...</p>
+    <div class="slide">
+        <h1>Slide 1</h1>
+        <img src="chart.png" alt="Chart">
     </div>
-    <div class="page">
-        <h1>Details</h1>
-        <p>Content...</p>
+    
+    <div class="slide">
+        <h1>Slide 2</h1>
+        <img src="graph.png" alt="Graph">
     </div>
 </body>
 </html>
 ```
 
-### Social Media Infographic
+### For Reports (9:16)
+
 ```html
 <!DOCTYPE html>
 <html>
 <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, orientation=portrait">
     <style>
         body {
-            width: 1080px;
-            height: 1080px;
-            margin: 0;
-            display: flex;
-            align-items: center;
-            justify-content: center;
+            font-family: Arial, sans-serif;
+            padding: 20px;
+        }
+        .page {
+            min-height: 100vh;
         }
     </style>
 </head>
 <body>
-    <div style="text-align: center;">
-        <h1>Your Infographic</h1>
-    </div>
+    <section class="page">
+        <h1>Annual Report 2024</h1>
+        <img src="logo.png" alt="Logo" style="width: 200px;">
+        <p>Report content...</p>
+    </section>
 </body>
 </html>
 ```
 
----
+## 🎯 Image Handling
 
-## 🎉 Key Takeaways
+### Supported Formats
+- PNG, JPG/JPEG
+- GIF, SVG
+- WebP, BMP
 
-1. **Always use print media emulation** - It's critical for proper PDF generation
-2. **Auto-detection is your friend** - Let the system choose the best settings
-3. **CSS page breaks work** - When properly configured with print emulation
-4. **Test with real content** - Different content types need different approaches
-5. **Use semantic HTML** - `<thead>`, `<section>`, etc. help with page breaks
-6. **Embed resources** - For self-contained PDFs, embed images and fonts
+### Image Path Examples
 
----
+Your HTML can have **any** of these formats:
+```html
+<!-- All of these work! -->
+<img src="logo.png">
+<img src="images/logo.png">
+<img src="../../../assets/images/logo.png">
+<img src="./photos/image.jpg">
+
+<!-- CSS backgrounds too -->
+<div style="background-image: url('bg.jpg')"></div>
+<div style="background-image: url('../images/bg.jpg')"></div>
+```
 
-## 📚 Additional Resources
+Just upload the images:
+```bash
+curl -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \
+  -F "html_file=@index.html" \
+  -F "images=@logo.png" \
+  -F "images=@bg.jpg" \
+  -o output.pdf
+```
 
-- [Puppeteer PDF API Documentation](https://pptr.dev/api/puppeteer.pdfoptions)
-- [CSS Paged Media Module](https://www.w3.org/TR/css-page-3/)
-- [MDN: page-break-inside](https://developer.mozilla.org/en-US/docs/Web/CSS/page-break-inside)
-- [Chromium Print CSS Support](https://bugs.chromium.org/p/chromium/issues/list?q=component:Blink%3ECSS%3EPrint)
+The API automatically:
+1. Extracts filenames from paths
+2. Normalizes all references to simple filenames
+3. Saves images to the same directory as HTML
+4. Generates PDF with all images embedded
 
----
+## 🔧 Troubleshooting
+
+### Images Not Showing
+- Ensure image filenames match exactly (case-sensitive)
+- Upload ALL images referenced in your HTML
+- Check that image paths are normalized (the API does this automatically)
+
+### Wrong Aspect Ratio
+- Set `auto_detect=false` and specify `aspect_ratio` manually
+- Check HTML for viewport meta tags that might override
+
+### Page Breaks in Wrong Places
+- Add `class="no-page-break"` to elements that should stay together
+- Use `class="page-break"` to force breaks at specific points
+
+### PDF Too Large
+- Optimize images before uploading (compress, resize)
+- Use appropriate image formats (WebP for photos, PNG for graphics)
+
+## 📊 Response Headers
+
+The API includes useful metadata in response headers:
+
+- `X-Aspect-Ratio`: Detected or specified aspect ratio
+- `X-Path-Replacements`: Number of image paths normalized
+- `X-PDF-Size`: Size of generated PDF in bytes
+
+**Example:**
+```bash
+curl -I -X POST https://abdallalswaiti-htmlpdfs.hf.space/convert \
+  -F "html_file=@test.html"
+
+# Response headers:
+# X-Aspect-Ratio: 9:16
+# X-Path-Replacements: 3
+# X-PDF-Size: 245678
+```
+
+## 🛠️ Technical Details
+
+- **Engine**: Puppeteer (Chromium-based)
+- **Backend**: FastAPI (Python)
+- **Max Timeout**: 60 seconds per conversion
+- **Page Sizes**:
+  - 16:9 → A4 Landscape (297mm × 210mm)
+  - 9:16 → A4 Portrait (210mm × 297mm)
+  - 1:1 → Square (210mm × 210mm)
+
+## 📄 License
+
+This API is provided as-is for public use on Hugging Face Spaces.
 
-## 🚀 Deployment Checklist
+## 🤝 Support
 
-- [ ] Replace `puppeteer_pdf.js` with new version
-- [ ] Replace `app.py` with enhanced version
-- [ ] Test with multi-page document
-- [ ] Test with single-page infographic
-- [ ] Test with different aspect ratios
-- [ ] Test auto-detection
-- [ ] Verify table header repetition
-- [ ] Check page break behavior
-- [ ] Test with embedded images
-- [ ] Monitor server logs for errors
-- [ ] Test production workload
+For issues or questions, please visit the [Space discussion page](https://huggingface.co/spaces/abdallalswaiti/htmlpdfs/discussions).
 
 ---
 
-**Version**: 2.0.0  
-**Last Updated**: October 2025  
-**Compatibility**: Puppeteer 23.x, Node.js 20.x
+**Made with ❤️ using FastAPI and Puppeteer**