generate-import-html（generate import HTML 命令行）

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-metadata div 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 (or og:title) with first H1 on page
• If matches first H1 → Omit (platform defaults to H1)
• If differs → Include as title property

Description:

• Compare source description (or og:description) with first paragraph
• If matches first paragraph → Consider omitting (platform defaults to first paragraph)
• If differs OR more descriptive → Include as description property
• 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 image property
• 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 canonical property

Tags:

• Map article:tag or keywords → comma-separated tags property

Properties to SKIP (platform auto-populates):

• og:url, og:title, og:description, twitter:title, twitter:description, twitter:image
• viewport, 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