Content is user-generated and unverified.

HTML Content Import Feature Specification

User Story

"As a marketer, I'd like to upload HTML content that I've prepared on another tool/platform."

1. Feature Overview

1.1 Purpose

Enable marketers to import pre-built HTML content (emails and onsite content) from external tools by uploading structured file packages.

1.2 Scope

  • Support for Email and Onsite content types
  • Automatic asset processing and cloud migration
  • Validation and error handling
  • Preview and editing capabilities post-import

2. Technical Specifications

2.1 Supported File Structures

2.1.1 Email Content

email-content.zip
├── index.html (required)
├── style.css (optional, embedded styles preferred)
├── images/
│   ├── logo.png
│   ├── banner.jpg
│   └── icon.svg

2.1.2 Onsite Content

onsite-content.zip
├── index.html (required)
├── style.css (optional)
├── script.js (optional)
├── images/
│   ├── hero-image.jpg
│   ├── product-1.png
│   └── background.svg

2.2 File Requirements

2.2.1 General Requirements

  • File Format: ZIP archive only
  • Maximum Size: 25MB per upload
  • Structure: Flat structure (no nested subfolders except for images)
  • HTML File: Must contain a single HTML file named index.html

2.2.2 Supported Asset Types

  • Images: PNG, JPG, JPEG, GIF, SVG, WebP
  • Stylesheets: CSS files
  • Scripts: JavaScript files (onsite only)
  • Maximum individual file size: 5MB

2.3 Image Processing Workflow

2.3.1 Image Upload Strategy

  1. Extract all images from the ZIP file
  2. Upload to AWS S3 with unique identifiers
  3. Generate CDN URLs for each uploaded image
  4. Update HTML references to point to CDN URLs

2.3.2 Image Reference Handling

javascript
// Before processing
<img src="./images/logo.png" alt="Logo">
<img src="images/banner.jpg" alt="Banner">
<img src="hero-image.png" alt="Hero">

// After processing
<img src="https://cdn.ourplatform.com/assets/abc123/logo.png" alt="Logo">
<img src="https://cdn.ourplatform.com/assets/abc123/banner.jpg" alt="Banner">
<img src="https://cdn.ourplatform.com/assets/abc123/hero-image.png" alt="Hero">

2.3.3 Missing Image Handling

  • Option A: Replace with placeholder image and flag for user attention
  • Option B: Leave original src intact and display warning
  • Option C: Remove image tag and log error
  • Recommended: Option A with user notification

3. UX Flow Specification

3.1 Entry Points

  1. Content Creation Dashboard → "Create New" → "Import from File"
  2. Content Type Selection → "Import HTML Content"
  3. Quick Actions Menu → "Import Content"

3.2 Step-by-Step User Journey

Step 1: Content Type Selection

┌─────────────────────────────────────┐
│     Choose Content Type             │
├─────────────────────────────────────┤
│  ○ Email Campaign                   │
│  ○ Landing Page/Onsite Content      │
│                                     │
│  [Continue]                         │
└─────────────────────────────────────┘

Step 2: File Upload Interface

┌─────────────────────────────────────┐
│     Upload HTML Content             │
├─────────────────────────────────────┤
│  ┌─────────────────────────────────┐ │
│  │     Drag & Drop Zone            │ │
│  │                                 │ │
│  │  📁 Drop your ZIP file here     │ │
│  │     or click to browse          │ │
│  │                                 │ │
│  │  Supported: .zip (max 25MB)     │ │
│  └─────────────────────────────────┘ │
│                                     │
│  File Requirements:                 │
│  • Single HTML file (index.html)   │
│  • Images in root or images folder │
│  • CSS/JS files in root            │
└─────────────────────────────────────┘

Step 3: Processing & Validation

┌─────────────────────────────────────┐
│     Processing Content...           │
├─────────────────────────────────────┤
│  ✓ Extracting files                 │
│  ✓ Validating structure             │
│  ⏳ Uploading images to CDN         │
│  ⏳ Processing HTML content         │
│  ⏳ Updating asset references       │
│                                     │
│  [████████░░] 80%                   │
└─────────────────────────────────────┘

Step 4: Review & Confirmation

┌─────────────────────────────────────┐
│     Import Summary                  │
├─────────────────────────────────────┤
│  Content Type: Email Campaign       │
│  Files Processed: 8                 │
│  Images Uploaded: 5                 │
│  Warnings: 1                        │
│                                     │
│  ⚠️  1 image reference not found:   │
│     "missing-icon.png"              │
│                                     │
│  [Preview Content] [Import Anyway]  │
│  [Cancel Import]                    │
└─────────────────────────────────────┘

Step 5: Content Preview & Editing

┌─────────────────────────────────────┐
│     Content Preview                 │
├─────────────────────────────────────┤
│  [Desktop] [Tablet] [Mobile]        │
│                                     │
│  ┌─────────────────────────────────┐ │
│  │     Rendered HTML Preview       │ │
│  │                                 │ │
│  │  [Content displays here]        │ │
│  │                                 │ │
│  └─────────────────────────────────┘ │
│                                     │
│  [Edit Content] [Save & Continue]   │
│  [Back to Upload]                   │
└─────────────────────────────────────┘

3.3 Error Handling UX

3.3.1 Upload Errors

┌─────────────────────────────────────┐
│     Upload Failed                   │
├─────────────────────────────────────┤
│  ❌ File validation failed          │
│                                     │
│  Issues found:                      │
│  • No index.html file found        │
│  • File size exceeds 25MB limit    │
│  • Unsupported file format         │
│                                     │
│  [Try Again] [View Requirements]    │
└─────────────────────────────────────┘

3.3.2 Processing Warnings

┌─────────────────────────────────────┐
│     Import Completed with Warnings  │
├─────────────────────────────────────┤
│  ⚠️  Some issues were found:        │
│                                     │
│  Missing Images (2):                │
│  • background-pattern.png          │
│  • social-icon.svg                 │
│                                     │
│  Large Files (1):                   │
│  • hero-banner.jpg (4.2MB)         │
│                                     │
│  [View Details] [Continue Anyway]   │
│  [Fix Issues]                       │
└─────────────────────────────────────┘

4. Technical Implementation Details

4.1 Backend Processing Pipeline

4.1.1 File Validation

python
def validate_zip_structure(zip_file):
    required_files = ['index.html']
    allowed_extensions = ['.html', '.css', '.js', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp']
    
    # Check for required files
    # Validate file extensions
    # Check file sizes
    # Verify no nested folders (except images/)

4.1.2 Asset Processing

python
def process_assets(extracted_files, content_type):
    images = extract_images(extracted_files)
    uploaded_images = upload_to_s3(images)
    
    html_content = update_image_references(
        html_file=extracted_files['index.html'],
        image_mapping=uploaded_images
    )
    
    return {
        'html': html_content,
        'assets': uploaded_images,
        'warnings': check_missing_references(html_content)
    }

4.2 Frontend Implementation

4.2.1 File Upload Component

javascript
const FileUploader = {
  acceptedTypes: '.zip',
  maxSize: 25 * 1024 * 1024, // 25MB
  onDrop: handleFileUpload,
  validation: validateFileStructure,
  progressCallback: updateProgress
}

4.2.2 Preview Component

javascript
const ContentPreview = {
  renderModes: ['desktop', 'tablet', 'mobile'],
  sanitizeHTML: true,
  allowedTags: [...], // Email-safe HTML tags
  onEdit: openContentEditor
}

5. Error Handling & Edge Cases

5.1 File Structure Issues

  • No index.html: Show clear error message with file structure requirements
  • Multiple HTML files: Use index.html, warn about others
  • Nested folders: Flatten structure or show error based on depth

5.2 Image Reference Issues

  • Relative paths: Support ./, ../, and direct references
  • Case sensitivity: Handle case mismatches in file names
  • URL encoded paths: Decode URLs properly
  • External images: Option to download and host locally

5.3 Content Validation

  • Email compatibility: Warn about unsupported CSS/HTML for email
  • File size optimization: Suggest compression for large images
  • Performance warnings: Flag heavy content for onsite use

6. Success Metrics & Testing

6.1 Success Criteria

  • Upload success rate > 95%
  • Processing time < 30 seconds for typical files
  • User completion rate > 80%
  • Support ticket reduction by 25%

6.2 Test Cases

  1. Happy Path: Standard zip with HTML and images
  2. Missing Images: HTML references non-existent images
  3. Large Files: Test file size limits and performance
  4. Malformed ZIP: Corrupted or invalid ZIP files
  5. Complex HTML: Rich content with CSS/JS dependencies
  6. Edge Cases: Empty files, special characters, unicode

7. Future Enhancements

7.1 Phase 2 Features

  • Template detection: Auto-categorize imported content
  • Bulk import: Process multiple ZIP files simultaneously
  • Version control: Track changes to imported content
  • Integration APIs: Direct import from popular tools

7.2 Advanced Processing

  • CSS optimization: Inline critical CSS for emails
  • Image optimization: Auto-compress and format conversion
  • Code cleanup: Remove unused CSS/JS
  • Accessibility checks: Validate for WCAG compliance

Appendix A: File Structure Examples

A.1 Valid Email Package

email-template.zip
├── index.html
├── logo.png
├── header-bg.jpg
└── social-icons.png

A.2 Valid Onsite Package

landing-page.zip
├── index.html
├── styles.css
├── script.js
├── hero-image.jpg
├── product-shot.png
└── favicon.ico

A.3 Invalid Structure Examples

❌ nested-folders.zip
├── templates/
│   └── index.html
└── assets/
    └── images/
        └── logo.png

❌ multiple-html.zip
├── page1.html
├── page2.html
└── main.html

❌ no-html.zip
├── styles.css
├── script.js
└── images/
    └── banner.jpg
Content is user-generated and unverified.
    HTML Content Import - Specification & UX Flow | Claude