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:
- Visual reference (PNG image) - Page layout and visual hierarchy
- Text data (rich_extraction.json) - Accurate text content and formatting metadata
- 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
-
Prepare three input files
- Load
02_page_XX.png(image file) - Load
01_rich_extraction.json(text spans with metadata) - Load
03_page_XX_ascii.txt(structure preview)
- Load
-
Construct AI prompt
- Attach PNG image as visual reference
- Include extracted text data (JSON)
- Include ASCII preview (text representation)
- Provide specific generation requirements
-
Invoke Claude API with complete context
- Send multi-modal prompt (text + image)
- Request semantic HTML5 output
- Specify CSS classes and structure requirements
-
Parse and save generated HTML
- Extract HTML from AI response
- Validate basic well-formedness
- Save to persistent file with metadata
-
Log generation metadata
- Record AI model used
- Timestamp generation
- List input files used
- 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.
```html
<!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