ai-html-generate

AI HTML Generate Skill

Purpose

This skill leverages AI's probabilistic generation capabilities to recreate PDF pages as semantic HTML. The AI receives three complementary inputs that together provide complete context:

1. Visual reference (PNG image) - Page layout and visual hierarchy
2. Text data (rich_extraction.json) - Accurate text content and formatting metadata
3. Structural preview (ASCII text) - Logical layout and element relationships

This three-input approach ensures the AI understands not just what text to include, but how it should be structured semantically in HTML.

The output is probabilistic (AI-generated), but will be made deterministic by validation gates in subsequent skills.

What to Do

1. Prepare three input files
2. Load 02_page_XX.png (image file)
3. Load 01_rich_extraction.json (text spans with metadata)
4. Load 03_page_XX_ascii.txt (structure preview)

1. Construct AI prompt
2. Attach PNG image as visual reference
3. Include extracted text data (JSON)
4. Include ASCII preview (text representation)
5. Provide specific generation requirements

1. Invoke Claude API with complete context
2. Send multi-modal prompt (text + image)
3. Request semantic HTML5 output
4. Specify CSS classes and structure requirements

1. Parse and save generated HTML
2. Extract HTML from AI response
3. Validate basic well-formedness
4. Save to persistent file with metadata

1. Log generation metadata
2. Record AI model used
3. Timestamp generation
4. List input files used
5. Store any confidence indicators from AI

Input Files (From Previous Skills)

Input 1: Rendered PDF Page (PNG)

File: output/chapter_XX/page_artifacts/page_YY/02_page_XX.png

• High-resolution rendering of PDF page
• 300+ DPI for visual clarity
• Shows actual page appearance
• Used for visual layout understanding

Input 2: Rich Extraction Data (JSON)

File: output/chapter_XX/page_artifacts/page_YY/01_rich_extraction.json

• Text spans with complete metadata
• Font names, sizes, bold/italic flags
• Position information (bounding boxes)
• Sequence and relationships

Input 3: ASCII Preview (Text)

File: output/chapter_XX/page_artifacts/page_YY/03_page_XX_ascii.txt

• Text-based structural representation
• Heading hierarchy marked
• Lists and bullets identified
• Paragraph flow documented
• Element types annotated

AI Prompt Template

The prompt sent to Claude:

You are recreating a PDF textbook page as semantic HTML5.

You have three pieces of information about this page:
1. A visual rendering (PNG image) - to understand layout
2. Parsed text data (JSON) - to ensure accuracy
3. An ASCII structure preview (text) - to understand element relationships

VISUAL REFERENCE:
[PNG Image Attached]

PARSED TEXT DATA:
[JSON Attached]

STRUCTURAL PREVIEW:
[ASCII Text Attached]

TASK:
Generate semantic HTML5 that accurately recreates this page.

REQUIREMENTS:

1. HTML5 Structure:
   - Proper DOCTYPE, html, head, body tags
   - Meta charset="UTF-8"
   - Meta viewport for responsive design
   - Title tag with descriptive text

2. Content Wrapper:
   - Single <div class="page-container"> wrapper
   - Single <main class="page-content"> for all content
   - No page breaks or paginated structure

3. Semantic HTML Elements:
   - Use proper heading tags (h1-h6) based on hierarchy
   - Use <p> for paragraphs
   - Use <ul> and <li> for bullet lists
   - Use <table> if data tables present
   - Use <figure> and <figcaption> for images/exhibits

4. Semantic CSS Classes:
   Apply these classes based on detected element types:

   Page Structure:
   - page-container (main wrapper)
   - page-content (content area)
   - chapter-header (chapter opening section)
   - chapter-number (numeric chapter marker)
   - chapter-title (chapter main title)

   Content Elements:
   - section-heading (major section, h2)
   - subsection-heading (minor section, h3-h4)
   - paragraph (body text, p)
   - bullet-list (ul)
   - bullet-item (li)

   Navigation & Structure:
   - section-navigation (list of topics/sections)
   - nav-item (individual nav item)
   - section-divider (hr divider line)

   Special Elements:
   - exhibit (table or figure)
   - exhibit-table (actual table)
   - exhibit-title (figure/table caption)
   - image-placeholder (for embedded images)

5. Content Preservation & Boundary Integrity:
   - Include ALL text content from the parsed data
   - Preserve exact text (no paraphrasing or edits)
   - Maintain original structure and relationships
   - Do not omit or skip sections

   CRITICAL - PAGE BOUNDARY RULES:
   - Start page content EXACTLY where JSON starts it
   - End page content EXACTLY where JSON ends it
   - NEVER add bridging text, connectors, or completing phrases
   - NEVER invent transitional words or sentences
   - NEVER synthesize content to "smooth" page transitions
   - Pages may start or end mid-sentence - this is EXPECTED and CORRECT
   - If a sentence seems incomplete, that is the accurate page boundary
   - Every single word in your HTML MUST exist in the source JSON

6. Heading Hierarchy:
   - Follow logical hierarchy (h1 → h2 → h3 → h4)
   - No skipped levels (don't jump from h1 to h4)
   - Chapter title is h1 (if present)
   - Main sections are h2
   - Subsections are h3 or h4 as appropriate

7. List Formatting:
   - Wrap in <ul class="bullet-list">
   - Each item in <li class="bullet-item">
   - Preserve item order and grouping
   - Include all bullet text exactly

8. CSS Stylesheet Link:
   - Include: <link rel="stylesheet" href="../../styles/main.css">
   - Use relative path (two levels up to root)
   - This stylesheet provides all styling

9. Special Handling:
   - Bold text within paragraphs: Use <strong> tags
   - Italic text: Use <em> tags
   - Embedded images: Use <img> tags with src path and alt text
   - Exhibits/tables: Preserve structure and captions

OUTPUT FORMAT:

Return ONLY valid HTML5. Do not include explanations.

<!DOCTYPE html> <html lang="en"> <head> ... </head> <body> ... </body> </html>

VALIDATION:
- HTML must be valid HTML5
- All opening tags must have closing tags
- Class attributes must use correct class names
- All text content from JSON MUST be included
- NO TEXT MAY BE ADDED that doesn't exist in the source JSON extraction
- Coverage must be 99-100% (>100% indicates invented content = FAIL)
- Every single word must come from the extraction data

Process Flow

┌─ Load Input Files ─────────────────────┐
│ • 02_page_XX.png (image)               │
│ • 01_rich_extraction.json (text data)  │
│ • 03_page_XX_ascii.txt (structure)     │
└────────┬────────────────────────────────┘
         │
         ▼
┌─ Construct Prompt ─────────────────────┐
│ • Attach PNG image                     │
│ • Include JSON data                    │
│ • Include ASCII preview                │
│ • Add generation requirements          │
└────────┬────────────────────────────────┘
         │
         ▼
┌─ Invoke Claude API ────────────────────┐
│ • Multi-modal prompt                   │
│ • Vision + Text understanding          │
│ • Deterministic system instructions    │
└────────┬────────────────────────────────┘
         │
         ▼
┌─ Extract & Save HTML ──────────────────┐
│ • Parse AI response                    │
│ • Extract HTML block                   │
│ • Basic validation (tag closure)       │
│ • Save to 04_page_XX.html              │
└────────┬────────────────────────────────┘
         │
         ▼
┌─ Log Generation Metadata ──────────────┐
│ • Model name and version               │
│ • Input file references                │
│ • Timestamp                            │
│ • Save to 05_generation_metadata.json  │
└────────┬────────────────────────────────┘
         │
         ▼
┌─ GATE 1: Verify Text Content ──────────┐
│ MANDATORY - DO NOT SKIP                │
│                                        │
│ Run per-page text ve