improve file formats

Author: mscoutermarsh

guides/file-formats.md

@@ -5,34 +5,114 @@ permalink: /guides/file-formats/
 parent: Guides
 nav_order: 2
 description: >-
-  HTML/CSS to Image supports converting html into png, jpg or webp. Learn how to specify the format of your image.
+  Learn about supported image formats (PNG, JPG, WebP) and how to optimize your image delivery.
 ---
-# File formats
+
+# Image File Formats
 {: .no_toc }
 {: .fs-9 }
 
-Convert images from HTML to jpg, png or webp.
+Choose the right format for your use case
 {: .fs-6 .fw-300 }
 
 <hr>
 
-## File formats
+Table of contents
+{: .text-delta }
+- TOC
+{:toc}
+
+<hr>
+
+## Supported Formats
+
+The API supports three image formats:
+- PNG (default)
+- JPG
+- WebP
+
+To specify a format, add the appropriate file extension to your image URL:
+
+| Format | Example URL | Best For |
+|:-------|:------------|:---------|
+| PNG | `https://hcti.io/v1/image/abc123.png` | Screenshots, images with transparency |
+| JPG | `https://hcti.io/v1/image/abc123.jpg` | Photos, complex images with no transparency |
+| WebP | `https://hcti.io/v1/image/abc123.webp` | Modern web applications, optimal compression |
+
+{% include hint.md title="Default Format" text="If no extension is specified, the API will return a PNG image." %}
+
+## Format Characteristics
+
+### PNG
+- Lossless compression
+- Supports transparency
+- Larger file size
+- Best for:
+  - Screenshots
+  - Images with text
+  - Graphics with sharp edges
+  - Content requiring transparency
+
+### JPG
+- Lossy compression
+- No transparency support
+- Smaller file size
+- Best for:
+  - Photographs
+  - Complex images
+  - When transparency isn't needed
+  - When smaller file size is priority
+
+### WebP
+- Modern format
+- Supports transparency
+- Superior compression
+- Best for:
+  - Web applications
+  - Progressive loading
+  - Optimal performance
+  - Modern browsers
+
+## Automatic WebP Optimization
+
+All paid accounts receive automatic WebP optimization:
+
+1. Our edge servers detect the user's browser capabilities
+2. If WebP is supported, images are automatically served in WebP format
+3. Fallback formats are served for non-supporting browsers
 
-The API supports `jpg`, `png` and `webp`. If no file extension is passed, you'll get back a png by default. If you need a different file format, adjust the extension on the url.
+Benefits:
+- Improved page load times
+- Better SEO scores
+- Reduced bandwidth usage
+- No code changes required
 
-| **Format** | **Example** |
-| :--- | :--- |
-| jpg | `https://hcti.io/v1/image/a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e.jpg` |
-| png | `https://hcti.io/v1/image/a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e.png` |
-| webp | `https://hcti.io/v1/image/a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e.webp` |
+{% include hint.md title="Performance Tip" text="WebP typically provides 25-35% smaller file sizes compared to PNG/JPG while maintaining visual quality." %}
 
-## Automatic next-gen format (WebP) - enabled for all customers
+## Best Practices
 
-It's [recommend by Google to serve your images](https://web.dev/uses-webp-images/) in next-gen formats (such as WebP).
+### Format Selection
+1. **Default to PNG** for:
+   - Screenshots
+   - Text-heavy images
+   - When quality is critical
+   
+2. **Use JPG** for:
+   - Photos
+   - Complex images
+   - When file size is priority
+   
+3. **Enable WebP** for:
+   - Modern web applications
+   - Performance optimization
+   - Progressive enhancement
 
-- Improves your pagespeed
-- Increases SEO
+## Browser Support
 
-Our edge servers will detect the browser being used to download an image. If the browser supports WebP, the image will be served in WebP.
+| Format | Chrome | Firefox | Safari | Edge | IE11 |
+|:-------|:-------|:--------|:-------|:-----|:-----|
+| PNG | ✅ | ✅ | ✅ | ✅ | ✅ |
+| JPG | ✅ | ✅ | ✅ | ✅ | ✅ |
+| WebP | ✅ | ✅ | ✅ | ✅ | ❌ |
 
-- This is enabled for all paid customers.
+{% include code_footer.md version=1 %}