tomevault-io Generate Import HTML
Create plain HTML file with block structure from authoring analysis.
When to Use This Skill
Use this skill when:
- You have complete authoring analysis (all sequences have decisions)
- You have section styling validation (from authoring-analysis)
- Ready to generate the HTML file for preview
Invoked by: page-import skill (Step 4)
Prerequisites
From previous skills, you need:
- ✅ Authoring analysis with block selections (from authoring-analysis)
- ✅ Section styling decisions (from authoring-analysis Step 3e)
- ✅ metadata.json with paths and metadata (from scrape-webpage)
- ✅ cleaned.html with content (from scrape-webpage)
- ✅ Block structures fetched (from authoring-analysis Step 3d)
Related Skills
- page-import - Orchestrator that invokes this skill
- authoring-analysis - Provides authoring decisions and styling validation
- scrape-webpage - Provides metadata, paths, cleaned HTML, images
- preview-import - Uses this skill's HTML output
⚠️ CRITICAL REQUIREMENT: Complete Content Import
YOU MUST IMPORT ALL CONTENT FROM THE PAGE. PARTIAL IMPORT IS UNACCEPTABLE.
- ❌ NEVER truncate or skip sections due to length concerns
- ❌ NEVER summarize or abbreviate content
- ❌ NEVER use placeholders like ""
- ❌ NEVER omit content because the page is "too long"
- ✅ ALWAYS import every section from authoring analysis
- ✅ ALWAYS include all text, images, and structure from cleaned.html
- ✅ If you encounter length issues, generate the FULL HTML anyway
Validation requirement: You MUST verify that the number of sections in your HTML matches the number of sections from identify-page-structure. If they don't match, you have made an error.
HTML Generation Workflow
Structure Requirements
IMPORTANT CHANGE: The AEM CLI now automatically wraps HTML content with headful structure (head, header, footer). You MUST generate ONLY the section content.
What to generate:
- ✅ Section divs with content:
<div>...</div>(one per section) - ✅ Blocks as
<div class="block-name">with nested divs - ✅ Default content (headings, paragraphs, links, images)
- ✅ Section metadata blocks where validated in authoring-analysis
What NOT to generate:
- ❌ NO
<html>,<head>, or<body>tags - ❌ NO
<header>or<footer>elements - ❌ NO
<main>wrapper element - ❌ NO head content (meta tags, title, etc. - this comes from project's head.html)
Structure format:
<div>
<!-- Section 1 content -->
</div>
<div>
<!-- Section 2 content with section-metadata if needed -->
<div class="section-metadata">
<div>
<div>Style</div>
<div>grey</div>
</div>
</div>
<!-- Section 2 blocks/content -->
</div>
<div>
<!-- Section 3 content -->
</div>
For detailed block structure patterns: See ../page-import/resources/html-structure.md
Section Metadata Application
Apply validated decisions from authoring-analysis Step 3e:
WITH section-metadata (section provides container styling):
<div>
<div class="section-metadata">
<div>
<div>Style</div>
<div>dark</div>
</div>
</div>
<div class="tabs">
<!-- Tabs block content -->
</div>
</div>
WITHOUT section-metadata (background is block-specific):
<div>
<div class="hero">
<!-- Hero block content with its own dark background -->
</div>
</div>
Important:
- Only migrate visible body content sections (skip header, navigation, footer - auto-generated)
- Use consistent style names from identify-page-structure
- Apply validated decisions from authoring-analysis Step 3e - Skip section-metadata for single-block sections where background is block-specific
- Place
section-metadatadiv at the start of each section that needs styling - The metadata div will be processed and removed by the platform
- Each section is a separate top-level
<div>element
Page Metadata Block
Unless user explicitly requested to skip metadata, use the metadata extracted from scrape-webpage to generate a metadata block.
Process:
1. Review extracted metadata from metadata.json
2. Map each property to standard format:
Title:
- Compare source
title(orog:title) with first H1 on page - If matches first H1 → Omit (platform defaults to H1)
- If differs → Include as
titleproperty
Description:
- Compare source
description(orog:description) with first paragraph - If matches first paragraph → Consider omitting (platform defaults to first paragraph)
- If differs OR more descriptive → Include as
descriptionproperty - Check: 150-160 characters ideal
Image:
- Check source
og:image - If matches first content image → Consider omitting (platform defaults to first image)
- If custom social image → Include as
imageproperty - Ensure absolute URL or correct relative path
- Check: 1200x630 pixels recommended
Canonical:
- If points to same page URL → Omit (platform auto-generates)
- If points to different page → Include as
canonicalproperty
Tags:
- Map
article:tagorkeywords→ comma-separatedtagsproperty
Properties to SKIP (platform auto-populates):
og:url,og:title,og:description,twitter:title,twitter:description,twitter:imageviewport,charset,X-UA-Compatible(belong in head.html)
3. Generate metadata block HTML:
<div>
<div class="metadata">
<div>
<div>title</div>
<div>[Your mapped title]</div>
</div>
<div>
<div>description</div>
<div>[Your mapped description]</div>
</div>
<!-- Only include image if custom -->
<!-- Only include canonical if differs from page URL -->
<!-- Only include tags if present -->
</div>
</div>
Append metadata block as the last section div at the end of the HTML file.
Detailed guidance: See resources/metadata-extraction.md and resources/metadata-mapping.md
Images Folder Management (CRITICAL)
The images are currently in ./import-work/images/ and the HTML references them as ./images/.... You MUST handle the images folder correctly:
Step 1: Determine the correct images folder location
Based on paths.htmlFilePath from metadata.json:
- HTML file:
us/en/about.plain.html→ Images should be at:us/en/images/ - HTML file:
products/widget.plain.html→ Images should be at:products/images/ - HTML file:
index.plain.html→ Images should be at:images/
Rule: Images folder goes in the same directory as the HTML file.
Step 2: Copy the images folder
# Example: If HTML is at us/en/about.plain.html
mkdir -p us/en/images
cp -r ./import-work/images/* us/en/images/
Step 3: Verify image paths in HTML are correct
The HTML should already reference images as ./images/... which is correct for files in the same directory. No path changes needed in the HTML.
Example:
HTML location: us/en/about.plain.html
Images location: us/en/images/
Image reference in HTML: <img src="./images/abc123.jpg">
Result: ✅ Correct - browser resolves to us/en/images/abc123.jpg
Save HTML File
Save to: Use paths.htmlFilePath from metadata.json (e.g., us/en/about.plain.html)
Read the metadata.json file from scrape-webpage to get the correct file path.
Validation Checklist (MANDATORY)
Before proceeding to preview-import skill, verify:
- ✅ Section count: HTML has the same number of top-level
<div>sections as identified in identify-page-structure - ✅ All sequences: Every content sequence from authoring-analysis appears in the HTML
- ✅ No truncation: No "..." or "" or similar placeholders
- ✅ Complete text: All headings, paragraphs, and text from cleaned.html are present
- ✅ All images: Every image reference from the scraped page is included
- ✅ HTML file saved: HTML file written to disk at the correct path
- ✅ Images folder copied: Images folder exists in the same directory as the HTML file
- ✅ Images accessible: Verify that at least one image file exists in the copied images folder
If any validation check fails, STOP and fix before proceeding.
Output
This skill provides:
- ✅ HTML file at correct path (e.g.,
us/en/about.plain.html) - ✅ Images folder in same directory (e.g.,
us/en/images/) - ✅ Complete content import (all sections)
- ✅ Proper block structure
- ✅ Section metadata applied per validation
- ✅ Page metadata block included
Next step: Pass HTML file path to preview-import skill
Converted and distributed by TomeVault — claim your Tome and manage your conversions.