# HTML File Structure for Test Content When creating local `.plain.html` files for testing blocks in the `drafts/` folder, follow this structure to match how AEM Edge Delivery Services processes authored content. ## Important Change: Plain HTML Format **The AEM CLI now automatically wraps HTML content with the headful structure (head, header, footer).** When you create `.plain.html` files, you ONLY need to provide the section content. **What you create:** - ✅ Section divs with content: `

...

` (one per section) - ✅ Blocks as `

` with nested divs - ✅ Default content (headings, paragraphs, links, images) - ✅ Section metadata blocks when needed **What the AEM CLI adds automatically:** - ❌ ``, ``, `` tags - ❌ `

` and `

` elements - ❌ `

` wrapper - ❌ Head content (comes from project's head.html) ## Plain HTML Structure ```html

Page Heading

This is regular paragraph content.

Block content cell 1

Block content cell 2

More content after the block.

``` ## File Naming Convention **IMPORTANT:** HTML files must use the `.plain.html` extension: - ✅ `drafts/hero-test.plain.html` - ✅ `drafts/blocks/cards.plain.html` - ❌ `drafts/hero-test.html` (old format, no longer used) ## Running with Local HTML **Start dev server with:** ```bash aem up --html-folder drafts ``` **Preview URLs:** - File: `drafts/hero-test.plain.html` → URL: `http://localhost:3000/drafts/hero-test` - File: `drafts/blocks/cards.plain.html` → URL: `http://localhost:3000/drafts/blocks/cards` - **Special case:** `drafts/blog/index.plain.html` → URL: `http://localhost:3000/drafts/blog/` (NOT `/drafts/`) ## Section Structure Content is organized into **sections** (top-level `

` elements). ### Basic Sections ```html

``` **Important notes about sections:** - Sections can contain blocks, default content, or a mix of both - A single section can contain multiple blocks - There are no strict rules about when to create a new section vs. adding to an existing one - This varies by project and authoring practices - Some blocks may require or assume they are in their own section (check block documentation) ### Section Metadata Sections can include metadata to define styling and behavior using a special `section-metadata` div. **In HTML (using section-metadata div):** ```html

Style

dark

``` **In markdown (Section Metadata table):** ```markdown +------------------------------+ | Section Metadata | +------------------+-----------+ | style | dark | +------------------+-----------+ ``` **How it works:** - The `section-metadata` div is placed at the beginning of a section - It uses a nested div structure to represent key-value pairs (like a table) - The platform processes this metadata and applies it to the parent section - After processing, the `section-metadata` div is removed from the DOM - Metadata values become CSS classes or data attributes on the section **Common section styles:** - `light` - White or light background - `dark` - Dark background with light text - `grey` - Grey or off-white background - `accent` - Branded color background **Style naming best practices:** - Use consistent names across sections with same visual treatment - Don't create unique style names for every section - Example: If 3 sections have white backgrounds, use "light" for all 3 **Example with multiple sections:** ```html

Style

light

Welcome

Style

dark

Card 1

Card 2

Style

light

About Our Company

This section has default content, not blocks.

``` **For guidance on identifying sections and assigning styles:** Use the **page-decomposition** skill when migrating pages. ## Section Content Types Sections can contain any combination of: ### 1. Default Content Regular HTML elements like headings, paragraphs, lists, etc. ```html

Main Heading

Subheading

Paragraph with bold and italic text.

Unordered list item

Ordered list item

``` **Supported default elements:** - Headings: `

`, `

` - Paragraphs: `

` - Lists: `

` - Inline formatting: ``, ``, `` - Images: Use `` elements with `` and `` tags (see Images section below) - Code blocks: `
`, `` - Block quotes: `` ### 2. Blocks Blocks are `` elements with specific class names that trigger decoration logic. **Basic block structure:** ```html ``` **Block with variant:** ```html ``` **Multiple variants:** ```html ``` ### 3. Icons Icons are authored using the `:iconName:` syntax and are processed into `` elements with icon classes. **Author input:** ``` :profile: ``` **HTML output:** ```html ``` **Important notes about icons:** - Icons can be wrapped in links, strong, em, or other inline elements - The icon name corresponds to an SVG file in `/icons/` (e.g., `:profile:` → `/icons/profile.svg`) - Icon spans use two classes: `icon` (base class) and `icon-{name}` (specific icon) - Icons are inline elements and can be combined with text **Examples:** Icon in a link: ```html View Profile ``` Icon with emphasis: ```html Featured ``` Icon by itself: ```html ``` ### 4. Images Images should always use the `` element with `` elements for responsive images and format optimization. **Basic picture structure:** ```html ``` **Key aspects of picture elements:** - Multiple `` elements provide WebP format with fallbacks - Use `media` attributes for responsive breakpoints (typically `(min-width: 600px)` for desktop) - Include width query parameters (`?width=750` for mobile, `?width=2000` for desktop) - Add `format` and `optimize=medium` parameters for image optimization - The final `` element is the fallback - Always include `alt` attribute for accessibility - Use `loading="lazy"` for images below the fold, `loading="eager"` for above-the-fold images **Standard responsive breakpoints:** ```html ``` **Important notes:** - Place images in the `/media/` folder or appropriate project location - Always provide meaningful `alt` text for accessibility - Use `loading="eager"` only for hero/above-the-fold images - The platform's `createOptimizedPicture()` JavaScript helper generates this structure automatically in decoration code **Simplified picture format for examples:** For brevity, examples in this document may show simplified picture tags: ```html ``` In actual test files, you can use either: 1. The full responsive structure shown above (recommended for realistic testing) 2. The simplified format (acceptable for quick prototyping, though less realistic) ## Block Content Structure The internal structure of a block depends on its content model. Blocks typically use nested `` elements to represent the table-like structure from authoring. ### Simple Block Example A hero block with an image and text: ```html Hero Heading Hero description text ``` ### Block with Multiple Rows A cards block with multiple items: ```html Card 1 Title Card 1 description Card 2 Title Card 2 description Card 3 Title Card 3 description ``` ### Block Structure Mapping The nested `` structure in HTML corresponds to the table structure in authoring: **In document authoring (table):** ``` | Block Name | |-------------------| | Cell 1 | Cell 2 | | Cell 3 | Cell 4 | ``` **In HTML:** ```html Cell 1 Cell 2 Cell 3 Cell 4 ``` ## Complete Example Here's a complete example of a test `.plain.html` file for a hero block: **File:** `drafts/hero-test.plain.html` ```html Welcome to Our Site This is a compelling hero message that encourages visitors to take action. Get Started About This Test This page demonstrates the hero block in action. Dark Variant Hero Testing the dark variant of the hero block. ``` **Preview at:** `http://localhost:3000/drafts/hero-test` ## Important Notes **File location:** - Create test HTML files in the `drafts/` folder - Can be organized in subfolders: `drafts/blocks/hero/test.plain.html` - Always use `.plain.html` extension **Running with local HTML:** - Start dev server with: `aem up --html-folder drafts` - This tells the dev server to serve HTML files from the drafts folder - The CLI automatically wraps your plain HTML with head, header, and footer **Section organization:** - Sections can contain any mix of blocks and default content - No strict rules about section boundaries - depends on project and authoring needs - Some blocks may require being in their own section - check block documentation **Images:** - Use `` elements with proper responsive structure (see Images section) - Reference images from the `/media/` folder or appropriate location - Always include `alt` attributes for accessibility **Testing considerations:** - Test multiple variants in the same file by adding multiple sections - Include edge cases in your test content - Use realistic content, not placeholder text **Content model alignment:** - The HTML structure must match your block's expected content model - Consult your content model documentation when structuring blocks - The decoration JavaScript will process this structure at two levels: - Page-level decoration (e.g., `decorateMain` in `scripts.js`) processes all content - Block-specific decoration (`blocks/{block-name}/{block-name}.js`) processes individual blocks - Classes and enhanced markup are typically added during decoration, not in the authored HTML ## When to Create CMS Content Instead Local HTML files are useful for quick iteration, but remember: - **For PRs:** You need actual CMS content for PSI validation links - **For documentation:** CMS content can serve as author documentation - **For collaboration:** CMS content is easier for non-developers to review Always plan to create CMS content before finalizing your PR, even if you start with local HTML for rapid development.