aem-markup-sections-blocks

AEM Markup, Sections, and Blocks Architecture

APPLY: EVERY QUERY - CRITICAL STRUCTURE RULE

Overview

Based on AEM's markup documentation, our architecture follows a structured approach for content organization and block development that balances author simplicity with developer flexibility.

Document Structure Hierarchy

1. Default Content (Preferred)

Keep as much content as default content as possible - this is the natural authoring experience.

Default content includes:

• Headings (<h1> - <h6>)
• Body text and paragraphs
• Lists (<ul>, <ol>)
• Images with responsive <picture> tags
• Links and emphasis (<em>, <strong>)
• Natural semantic markup

Author Experience: Content creators work with familiar Word/Google Docs semantics without needing to understand blocks.

2. Sections (Layout Grouping)

Purpose: Group content visually (background colors, layout changes)

Section Rules:

• Separated by horizontal rules (---) in authoring
• Contain multiple blocks and/or default content
• Minimal JavaScript interaction beyond CSS styling
• Can include Section Metadata for data attributes and styling

Example Section Metadata:

Section Metadata
- Style: dark, wide
- Background: blue

DOM Output:

<div class="section dark wide" data-background="blue">
  <!-- section content -->
</div>

3. Blocks (Component Logic)

Purpose: Componentized functionality and styling

Block Architecture:

• Block name = folder name = CSS class = filename
• CSS file: blockname.css (scoped to .blockname class)
• JavaScript file: blockname.js (ESM module with default export)
• DOM structure: Nested <div> tags for rows/columns

Block Development Standards

Block File Structure

blocks/
  blockname/
    blockname.css
    blockname.js

Block JavaScript Pattern (REQUIRED)

// ✅ REQUIRED: Standard block export pattern
export default async function init(el) {
  // 1. DOM enhancement first (for LCP)
  const basicStructure = createBasicUI(el);
  el.append(basicStructure);
  
  // 2. Data fetching second (progressive enhancement)
  const data = await fetchData();
  enhanceWithData(basicStructure, data);
}