Modeling Content

Content Modeling for AEM Edge Delivery Blocks

This skill guides you through designing content models for AEM Edge Delivery Services blocks. A content model defines the HTML table structure that authors work with when creating content in their CMS (Google Docs, SharePoint, etc.).

Related Skills

• content-driven-development: This skill is typically invoked FROM the CDD skill during Phase 1 (Content Model Design)
• building-blocks: After content modeling is complete, this skill handles implementation
• block-collection-and-party: Use to find similar blocks and their content models for reference

When to Use This Skill

Use this skill when:

• Creating new blocks and need to design the author-facing content structure
• Modifying existing blocks in ways that change what authors work with
• Reviewing content models for conformance to best practices
• Migrating or refactoring content models

Note: This skill is usually invoked automatically by the content-driven-development skill at Step 1.2. If you're not already in a CDD workflow and are creating a new block, consider invoking the CDD skill first.

Core Principles

A good content model is:

• Semantic: Structure carries meaning on its own without decoration
• Predictable: Authors, developers, and agents all know what to expect
• Reusable: Works across authoring surfaces and projects

Prerequisites

Before designing a content model, ensure you understand:

1. Block Purpose: What is this block meant to accomplish? 2. Content Requirements: What content elements are needed (images, text, links, etc.)? 3. User Experience: How should this block appear and function on the page?

The Content Modeling Process

Step 1: Identify the Canonical Model Type(s)

AEM Edge Delivery has 4 canonical block models. While these cover the most common cases, sometimes the best approach is to support multiple models for the same block to accommodate different authoring workflows and content complexity.

Review the descriptions in resources/canonical-models.md and identify which model(s) fit best:

• Standalone: Best for distinct visual or narrative elements (Hero, Blockquote)
• Collection: Ideal for repeating semi-structured content (Cards, Carousel)
• Configuration: Use ONLY for API-driven or dynamic content where config controls display (Blog Listing, Search Results)
• Auto-Blocked: Good for simplifying authoring of complex structures and block nesting (Tabs, YouTube Embed)

Consider these questions as a starting point (note: content modeling is an art, not a science - use these as guidelines, not strict rules):

• Is this a unique, one-off element? → Often Standalone
• Is this a repeating list of similar items? → Often Collection
• Does this pull data from an API or require behavior configuration? → Likely Configuration
• Does this block require nesting other blocks, or use a complex structure that authors could more easily create as sections or default content that gets transformed into the block? → Consider Auto-Blocked

Important: Consider if multiple models should be supported. For example:

• Simple cases might work best as Collection
• Complex cases (with nested blocks) might need Auto-Blocked
• Both can be equally valid - let decoration code handle the variations

See resources/advanced-scenarios.md for patterns on supporting multiple models for one block.

Step 2: Design the Table Structure

Design your table structure following these key guidelines:

Key Guidelines:

• Limit to maximum 4 cells per row - group like elements into cells
• Apply semantic formatting (headings, bold, italic) to define meaning
• Prefer block variants over config cells
• Infer from context and use smart defaults to limit what authors must input
• Follow Postel's Law: "be conservative in what you do, be liberal in what you accept from others"
• Be flexible about the input structure authors provide. For example, in a hero block, all elements could be in one cell, split across 2 cells in one row, or in 2 separate rows - any of these can work with proper decoration code (it's just query selectors)
• Don't be overly prescriptive about structure when flexibility makes sense
• The goal is to make authoring easier, not to enforce rigid structures for developer convenience

For each canonical model:

Standalone blocks:

• Use rows or columns as needed for the unique structure
• Be flexible about how authors organize content - your decoration code can handle variations
• Use semantic formatting to identify elements (bold for headings, etc.) rather than rigid cell positions
• Example: Hero block where image and text could be in separate rows, separate columns, or even combined - decoration code uses query selectors to find what it needs

Collection blocks:

• Each row represents an item
• Columns define the parts of each item
• Keep columns consistent across all rows
• Example: Cards with columns for image, heading, description

Configuration blocks:

• Two-column key/value pairs for settings or parameters
• Keys in left column, values in right column
• Keep configuration minimal - only true behavioral settings
• Example: Blog Listing with keys like limit | 10, sort | date-desc, tags | technology,news

Auto-Blocked:

• Design for the simplest possible authoring experience
• Often uses sections and section metadata to provide context
• The pattern detection should feel "magical" to authors
• Example: Tabs block that auto-blocks from a section containing multiple H2 headings with content, using section metadata for styling options

Step 3: Validate Against Best Practices

Use this checklist to validate your content model:

• [ ] Uses the appropriate canonical model type
• [ ] Maximum 4 cells per row
• [ ] Semantic formatting defines meaning (not just visual styling)
• [ ] Model is predictable (clear what goes where)
• [ ] Model is reusable (works across different authoring tools)
• [ ] Smart defaults minimize required author input
• [ ] Avoids configuration cells unless truly needed for dynamic content
• [ ] Cell names/purposes are clear and meaningful
• [ ] Consider edge cases (empty cells, optional content, etc.)

Common Anti-Patterns to Avoid:

• ❌ Too many columns (>4 per row)
• ❌ Using Configuration model when Standalone or Collection would work
• ❌ Non-semantic cell content (e.g., "column1", "column2")
• ❌ Requiring authors to input data that could be inferred or defaulted
• ❌ Complex nested structures that confuse authors
• ❌ Models that only work in one specific authoring tool

Step 4: Document the Content Model

Provide the content model back to the calling skill (or user) in this format:

## Content Model: [Block Name]

### Block Type
[Standalone | Collection | Configuration | Auto-Blocked]

### Table Structure

| Block Name |
|------------|
| [Cell description] |
| [Cell description] | [Cell description] |

### How It Works
[Explain what authors create and how the table structure works. Describe the purpose of each row/column and any semantic formatting used.]

### Key Points
- [Important authoring guidelines]
- [Examples of semantic formatting (e.g., "bold text indicates the heading")]
- [Any flexibility in structure (e.g., "content can be in one cell or split across two")]
- [Common variants if applicable]

Important: This skill focuses on designing the content model. The calling skill (content-driven-development or building-blocks) will handle what to do with it next, such as creating test content or implementing the block.

Resources

• resources/canonical-models.md - The 4 canonical model types with detailed examples and best practices
• resources/advanced-scenarios.md - Supporting multiple models, progressive enhancement, and complex patterns

Example Workflow

Scenario: User needs to create a hero block with an image, heading, and call-to-action

Process:

1. Identify Model Type:

• This is likely a Standalone block (distinct visual element, typically appears once)
• Could also work as a simple Collection if multiple heroes are needed, but Standalone is more common

2. Design Structure:

• Start with a flexible approach that uses semantic formatting
• Authors could structure this multiple ways - decoration code will handle variations

3. Validate:

• ✅ Standalone model (appropriate for hero)
• ✅ Semantic formatting will identify elements (H1 for heading, links for CTA)
• ✅ Flexible structure - can work with different layouts
• ✅ Reusable (works in any authoring tool)
• ✅ Under 4 cells per row

4. Document and Return to Calling Skill:

   ## Content Model: Hero

   ### Block Type
   Standalone

   ### Table Structure
   | Hero |
   |------|
   | [Image] |
   | [Heading, description, and CTA] |

   ### How It Works
   Authors create a hero block using a simple table. The structure is flexible:
   - Image can be in its own row or column
   - Text content (heading, description, CTA) can be together or separated
   - Decoration code uses semantic formatting to identify elements:
     - H1 or bold text → heading
     - Regular paragraphs → description
     - Links → call-to-action

   ### Key Points
   - Use H1 or bold formatting for the main heading
   - Structure is flexible - all content in one row, split across two rows, or in columns all work
   - Image should be high-resolution (minimum 2000px wide for full-width heroes)
   - Variants available: `Hero (Dark)`, `Hero (Centered)`, etc.

Skill returns this content model to CDD or building-blocks skill for next steps.

Integration with Other Skills

Called from content-driven-development:

• CDD invokes this skill at Step 1.2 when new content models are needed
• After completing this skill, return to CDD to continue with content creation

Calls to other skills:

• May reference block-collection-and-party to find similar blocks for pattern inspiration
• Completed models are used by building-blocks during implementation

Key Takeaways

1. Choose the right canonical model first - this drives everything else 2. Keep it simple - authors should understand the model intuitively 3. Use semantic formatting - let the structure carry meaning 4. Validate ruthlessly - check against all best practices before finalizing 5. Document clearly - both the structure and the reasoning behind it

Content models are the foundation of author experience. Invest time here to create intuitive, maintainable structures that serve authors well.

Advanced Content Modeling Scenarios

This document covers common challenges in content modeling and their solutions. These scenarios go beyond the basic canonical models and address real-world complexity.

---

Challenge 1: Nested Blocks

The Problem: Sometimes a block needs to contain other blocks. Examples:

• Tabs where each tab contains a cards or columns block
• Accordions with complex content including multiple blocks

Solutions:

Solution A: Auto-Blocking with Sections

Authors create separate sections with section metadata. The auto-blocking code merges them into one block with nested content.

Example: Tabs with nested blocks

| Section Metadata |
|------------------|
| style | tabs |

## Getting Started

Welcome to our platform! Here's how to begin.

| Hero |
|------|
| ![Welcome](welcome.jpg) | # Start Here<p>Your journey begins now.</p> |

---

| Section Metadata |
|------------------|
| style | tabs |

## Features

| Cards |
|-------|
| ![Feature 1](f1.jpg) | ## Real-time Collaboration<p>Work together seamlessly.</p> |
| ![Feature 2](f2.jpg) | ## Advanced Analytics<p>Insights at your fingertips.</p> |

Multiple consecutive sections with style | tabs metadata get merged into one tabs block, with each section becoming one tab. Any blocks within the sections are preserved as nested blocks.

Solution B: Fragments

Authors create the outer block and link to a fragment containing the inner blocks.

Example: Accordion with fragment

| Accordion |
|-----------|
| ## How do I get started? | [Getting started guide](../fragments/getting-started) |
| ## What features are available? | [Feature overview](../fragments/features) |

The fragment documents contain the detailed content with multiple blocks, which get embedded into the accordion items.

When to use which:

• Auto-blocking: When authors naturally think in sections and the pattern is common/predictable
• Fragments: When the nested content is complex, reused across pages, or managed separately

---

Challenge 2: Item-Level Configurations in Collections

The Problem: In a collection block, each item might need its own configuration - not content, but behavioral or styling settings. This is different from the item's actual content (text, images, links). Examples:

• Each card in a grid could potentially be "featured" with different sizing
• Each accordion item needs to specify whether it starts expanded or collapsed
• Each carousel slide might have different transition effects or display durations

The challenge is that this configuration isn't really content that authors should have to think about for every item, but you need a way to specify it when needed.

Solutions:

Solution A: Variant Lists

Use variants at the block level to specify which items get special configuration.

Example: Cards with featured items

| Cards (Featured-2, Featured-4) |
|--------------------------------|
| ![Product 1](p1.jpg) | ## Standard Product<p>Regular card styling.</p> |
| ![Product 2](p2.jpg) | ## Featured Product<p>This one stands out with larger size.</p> |
| ![Product 3](p3.jpg) | ## Another Product<p>Back to regular styling.</p> |
| ![Product 4](p4.jpg) | ## Also Featured<p>This one is also larger and featured.</p> |
| ![Product 5](p5.jpg) | ## Standard Product<p>Regular card styling.</p> |

The decoration code parses the variant list Featured-2, Featured-4 and applies the "featured" styling to items 2 and 4 (using 1-based indexing).

Example: Accordion with default-open items

| Accordion |
|-----------|
| ## First Question (Open) | The answer to the first question appears here. |
| ## Second Question | This one starts collapsed. |
| ## Third Question | Also starts collapsed. |

Solution B: Optional Configuration Cell

Add an additional (optional) column for configuration when variants aren't sufficient.

Example: Collection with per-item config

| Gallery |
|---------|
| ![Image 1](img1.jpg) | Beautiful sunset over mountains | |
| ![Image 2](img2.jpg) | City skyline at night | zoom-enabled |
| ![Image 3](img3.jpg) | Forest path in autumn | |

The third column is optional. When present, it configures that specific item (in this case, enabling zoom for image 2).

When to use which:

• Variants: When the configuration is simple styling/behavior that maps to CSS classes (Featured, Large, Open, etc.)
• Optional config cell: When the configuration is more complex or doesn't fit the variant pattern well
• Neither: If every (or nearly every) item needs unique configuration, those settings might actually be content that varies per item, not behavioral config - consider whether Collection is the right model

Trade-offs:

• Variants are more author-friendly and semantic
• Config cells are more flexible but less intuitive, and non-semantic
• Both add complexity - use sparingly, only when truly needed

---

Challenge 3: Lists

The Problem: Blocks often contain things that feel "list-like" to developers - repeating items that would naturally be rendered as <ul> or <ol> elements. However, authors often struggle to create list elements in their authoring tools (Google Docs, SharePoint, etc.), especially when list items are complex (like a list of related articles with images and links).

The key principle: Never require authors to create lists when they can be avoided. What looks like a list to a developer can often be better modeled as a Collection or other structure that's easier to author.

Reference: See Rule 5 from David's Model

Solutions:

The solution is almost always to use a Collection model, but the specific approach depends on the complexity of each item.

Solution A: Collection Block for Complex Items

When each "list item" has multiple parts (image, heading, description, link), use a Collection block.

Example: Related articles

| Related Articles |
|------------------|
| ![Article 1](article1.jpg) | ## Understanding Edge Delivery<p>Learn the basics of AEM Edge Delivery Services.</p><p>[Read more](article1)</p> |
| ![Article 2](article2.jpg) | ## Content Modeling Best Practices<p>Design content models that authors love.</p><p>[Read more](article2)</p> |
| ![Article 3](article3.jpg) | ## Performance Optimization<p>Make your site lightning fast.</p><p>[Read more](article3)</p> |

Each row is one article. Columns separate the parts (image, content). Decoration code renders this as cards or a list, depending on styling needs.

Solution B: Flexible Input for Simple Items

When each "list item" is simple (text only, or text with minimal formatting), support multiple authoring approaches.

Example: Recipe ingredients - support both approaches

Option 1: One item per line in one cell

| Recipe |
|--------|
| ![Finished dish](dish.jpg) |
| ## Chocolate Chip Cookies |
| <p>2 cups flour</p><p>1 cup butter</p><p>1 cup sugar</p><p>2 eggs</p><p>2 cups chocolate chips</p> |

Option 2: One item per row

| Recipe |
|--------|
| ![Finished dish](dish.jpg) |
| ## Chocolate Chip Cookies |
| 2 cups flour |
| 1 cup butter |
| 1 cup sugar |
| 2 eggs |
| 2 cups chocolate chips |

Both are valid. The decoration code handles both patterns - it checks if there's a <ul> or <ol> in one cell, or if there are multiple rows of simple text. This flexibility makes it easy for authors to copy/paste ingredients or type them however feels natural.

When to use which:

• Collection for complex items (Solution A): When each item has multiple distinct parts (image + heading + description, or any combination that benefits from column structure)
• Flexible input for simple items (Solution B): When items are just text or links, and you want to make authoring as easy as possible by supporting multiple input methods

Key takeaway: Don't make authors create formal list elements in their authoring tool. Use Collection models or flexible text input instead. Your decoration code can always render the final output as a <ul> or <ol> if that's the right semantic HTML.

---

Challenge 4: Forms

The Problem: Forms seem like Standalone blocks (distinct visual element, typically appears once) but have many input fields, which pushes them toward Configuration or Collection models. How do you balance author ease with the structural complexity of forms?

Solutions:

Forms are relatively uncommon in content-driven sites. When they do appear, consider these approaches in order of preference:

Solution A: External Form Services

For complex forms or forms requiring advanced features (multi-step, conditional logic, integrations), use external services like Marketo, HubSpot, Google Forms, etc. Embed them via iframe or integration blocks.

Solution B: Spreadsheet-Based Forms

Use a spreadsheet to define form fields, and create a Standalone form block that links to it.

Example: The form block

| Form |
|------|
| [Contact Form Fields](/forms/contact-form.json) |

Example: The spreadsheet (contact-form.xlsx)

In AEM, spreadsheets get published as JSON. The form block's decoration code fetches the JSON and builds the form dynamically. See the Block Collection for examples of this pattern.

Why this works:

• Separates form definition (spreadsheet) from form placement (block)
• Authors can manage form fields in a familiar spreadsheet interface
• Form definition is reusable across multiple pages
• Easy to update fields without touching content pages

Solution C: Configuration Model (Anti-Pattern, but Sometimes Necessary)

Use a Configuration block for one-off forms where a spreadsheet feels like overkill.

Example:

| Form |
|------|
| action | /submit-contact |
| fields | name,email,message |
| submit-label | Send Message |

Warning: This is non-semantic and requires authors to understand the configuration format. Only use for very simple, one-off forms that won't be reused or frequently modified.

When to use which:

• External services (Solution A): For complex forms or when integrating with marketing/CRM systems
• Spreadsheet (Solution B): For most custom forms, especially if reused or frequently updated
• Configuration (Solution C): Only for very simple one-off forms

---

Key Principles for Advanced Scenarios

When facing complex content modeling challenges:

1. Start simple: Can this be handled with a basic canonical model? Don't add complexity prematurely.

2. Prioritize author experience: The best technical solution isn't always the one that's easiest to author. Can authors understand this intuitively?

3. Be consistent: If you solve a problem one way for one block, use the same pattern for similar blocks.

4. Document edge cases: When supporting optional cells, variants, or multiple models, document what authors can expect.

5. Test with real authors: Complex models often reveal usability issues only when real people try to use them.

6. Consider alternatives: Sometimes the answer isn't a better content model, but a different feature (fragments, section metadata, auto-blocking, external tools).

The goal is always the same: make it easy for authors to create great content while giving developers the structure they need to build great experiences.

The 4 Canonical Block Models

AEM Edge Delivery Services has 4 canonical patterns for structuring block content. Choosing the right model is the foundation of creating effective, author-friendly content structures.

Model Selection Guide

---

1. Standalone Model

Description

Self-contained blocks using rows or columns as needed for their unique structure. Best for elements that appear once or a few times on a page with a distinct purpose.

Characteristics

• Unique, one-off structure
• Rows and columns organized for the specific content needs
• Each instance is typically different from others
• Structure carries the semantics of the content

When to Use

• Hero sections
• Blockquotes
• Feature callouts
• Unique page sections
• Any element with a distinct visual or narrative purpose

Good Example: Hero Block

| Hero |
|------|
| ![Hero image](hero.jpg) |
| # Welcome to Our Site |
| Discover amazing content and start your journey today. [Get Started](cta-link) |

Why this works:

• ✅ Uses semantic formatting: H1 identifies the heading, paragraphs for body text
• ✅ Flexible structure: could also work with image and text in columns, or all in one cell
• ✅ Decoration code can find elements using query selectors regardless of exact layout
• ✅ Author-friendly: natural content authoring

Note on flexibility: These variations would also work with proper decoration code:

• Image and text in separate columns: | ![Image](hero.jpg) | # Heading<p>Description text [CTA](link)</p> |
• All content in one cell: | ![Image](hero.jpg)<h1>Heading</h1><p>Description text [CTA](link)</p> |
• Image in one row, heading and text in another (as shown above)
• The key is semantic formatting (H1 for heading, paragraph text, links for CTA), not rigid cell positions

Bad Example: Hero Block (Anti-Pattern)

| Hero |
|------|
| ![Image](hero.jpg) | Welcome | Discover content | Get Started | /cta-link | dark |

Why this fails:

• ❌ 6 cells in one row (exceeds maximum of 4)
• ❌ Non-semantic: text split across multiple unlabeled cells
• ❌ Split related text across cells unnecessarily
• ❌ Configuration-style variant control in "dark" cell (should use block variant class)
• ❌ Unpredictable: authors must remember which cell is which
• ❌ Author-hostile: too many required cells, no semantic formatting

How to fix:

• Simplify to under 4 cells per row
• Use semantic formatting (H1 for heading, paragraphs for text, links for CTA) instead of splitting into separate cells
• Use block variant | Hero (Dark) | instead of config cell
• Let decoration code find elements via query selectors, don't require specific cell positions

---

2. Collection Model

Description

Each row represents an item, with columns defining the parts of that item. Ideal for repeating, semi-structured content where each instance follows the same pattern.

Characteristics

• Rows represent individual items
• Columns are consistent across all rows
• Items have the same structure but different content
• Easy to add/remove items by adding/removing rows

When to Use

• Card grids
• Carousels
• Image galleries
• Feature lists
• Team member listings
• Any repeating set of similar items

Good Example: Cards Block

| Cards |
|-------|
| ![Product 1](product1.jpg) | ## Product Name<p>High-quality product description goes here.</p><p>[Learn More](link1)</p> |
| ![Product 2](product2.jpg) | ## Another Product<p>Different product with its own description.</p><p>[Learn More](link2)</p> |
| ![Product 3](product3.jpg) | ## Third Product<p>More details about this product offering.</p><p>[Learn More](link3)</p> |

Why this works:

• ✅ Collection model: each row is one card
• ✅ 2 columns: image and content
• ✅ Consistent structure across all rows
• ✅ Semantic formatting: H2 for card title, paragraph text for description, links for CTA
• ✅ Easy to add/remove cards (add/remove rows)
• ✅ Within 4-cell maximum

Resulting structure:

• Each row becomes one card
• Column 1: Card image
• Column 2: Card heading (H2), description (paragraph), and CTA link - decoration code uses query selectors to identify each element

Bad Example: Cards Block (Anti-Pattern)

| Cards |
|-------|
| config | style | grid |
| ![Product 1](product1.jpg) |
| Product Name |
| High-quality product description |
| [Learn More](link1) |
| ![Product 2](product2.jpg) |
| Another Product |
| Different product description |
| [Learn More](link2) |

Why this fails:

• ❌ Mixing configuration row with content rows
• ❌ Non-semantic: first row should use block variant instead
• ❌ Each card uses 4 separate rows instead of 1 row with columns
• ❌ Unpredictable: hard to tell where one card ends and another begins
• ❌ Author-unfriendly: difficult to add/remove cards
• ❌ Requires counting rows to understand structure

How to fix:

• Remove config row, use variant: | Cards (Grid) |
• Use columns instead of rows for each card's parts
• One row = one complete card

---

3. Configuration Model

Description

Two-column key/value pairs for settings or parameters. Use ONLY for API-driven or dynamic content where configuration actually controls behavior or data fetching.

Characteristics

• Two columns: key (left) and value (right)
• Controls behavior, not content structure
• Often drives API calls or dynamic data
• Minimal visual content

When to Use

• Blog listings (sort order, filters)
• Search results (query parameters)
• Dynamic data displays
• API-driven components
• True behavioral configuration

⚠️ Important Warning

Do NOT use Configuration model when:

• Standalone or Collection model would work
• You're just displaying static content
• Configuration could be handled by block variants
• Authors are providing content, not controlling behavior

Configuration models are often overused. Always ask: "Does this truly need dynamic configuration, or am I just making authoring harder?"

Good Example: Blog Listing Block

| Blog Listing |
|--------------|
| limit | 10 |
| sort | date-desc |
| tags | technology,news |

Why this works:

• ✅ Truly configuration-driven (controls API query)
• ✅ Two-column key/value pairs
• ✅ No visual content (pure config)
• ✅ Controls dynamic behavior (fetch and display blog posts)
• ✅ Appropriate use case for Configuration model

Resulting behavior:

• Fetches 10 most recent posts
• Sorted by date descending
• Filtered to posts tagged with "technology" or "news"

Bad Example: Blockquote (Anti-Pattern)

| Blockquote |
|------------|
| text | The best way to predict the future is to invent it. |
| author | Alan Kay |
| style | bordered |
| background | light-gray |

Why this fails:

• ❌ This is static content, not dynamic configuration
• ❌ Should be Standalone model, not Configuration
• ❌ "style" and "background" should be block variants
• ❌ Forces authors to label their own content
• ❌ More complex than necessary

How to fix: Use Standalone model with semantic formatting:

| Blockquote (Bordered, Light) |
|-------------------------------|
| The best way to predict the future is to invent it. |
| *Alan Kay* |

• Use block variants for styling
• Use semantic formatting (italic) for attribution
• Let structure speak for itself

---

4. Auto-Blocked Model

Description

Content authored as default content that gets automatically converted into blocks based on pattern detection. Simplifies authoring of complex structures by hiding the "block-ness" from authors.

Characteristics

• Authors write standard content
• Pattern detection creates blocks automatically
• "Magical" author experience
• Good for common, predictable patterns
• Reduces authoring complexity

When to Use

• Tab interfaces (heading patterns)
• YouTube embeds (URL detection)
• Common content patterns
• Nested block structures
• Whenever you can hide complexity from authors

Good Example: Tabs (Auto-Blocked)

What authors write - three separate sections, each with section metadata:

| Section Metadata |
|------------------|
| style | tabs |

## Getting Started

Follow these steps to set up your account and configure your preferences.

| Hero |
|------|
| ![Welcome](welcome.jpg) | # Welcome<p>Start your journey here.</p> |

---

| Section Metadata |
|------------------|
| style | tabs |

## Advanced Features

Learn about advanced capabilities once you're comfortable with the basics.

- Feature 1: Real-time collaboration
- Feature 2: Advanced analytics
- Feature 3: Custom integrations

---

| Section Metadata |
|------------------|
| style | tabs |

## Troubleshooting

Common issues and how to resolve them quickly.

| Cards |
|-------|
| ![Issue 1](issue1.jpg) | ## Login Problems<p>How to reset your password.</p> |
| ![Issue 2](issue2.jpg) | ## Performance Issues<p>Tips for optimizing performance.</p> |

---

What gets created - auto-blocked into one tabs block:

<div class="tabs">
  <div>
    <div><h2>Getting Started</h2></div>
    <div>
      <p>Follow these steps to set up your account and configure your preferences.</p>
      <div class="hero"><!-- Hero block content --></div>
    </div>
  </div>
  <div>
    <div><h2>Advanced Features</h2></div>
    <div>
      <p>Learn about advanced capabilities once you're comfortable with the basics.</p>
      <ul>
        <li>Feature 1: Real-time collaboration</li>
        <li>Feature 2: Advanced analytics</li>
        <li>Feature 3: Custom integrations</li>
      </ul>
    </div>
  </div>
  <div>
    <div><h2>Troubleshooting</h2></div>
    <div>
      <p>Common issues and how to resolve them quickly.</p>
      <div class="cards"><!-- Cards block content --></div>
    </div>
  </div>
</div>

Why this works:

• ✅ Authors create natural sections (separated by ---) with H2 headings and content
• ✅ Section metadata (style | tabs) signals intent to auto-block
• ✅ Multiple consecutive sections with style | tabs metadata get merged into one tabs block
• ✅ Each section becomes one tab: H2 = tab title, everything else = tab content
• ✅ No need to understand block syntax
• ✅ Can mix default content and blocks within tab content
• ✅ Simplifies complex authoring
• ✅ Feels "magical" when it works

Good Example: YouTube Embed (Auto-Blocked)

What authors write:

![Video preview image](video-preview.jpg)
https://www.youtube.com/watch?v=dQw4w9WgXcQ

What gets created:

<div class="embed embed-youtube">
  <div>
    <div>
      <picture>
        <img src="video-preview.jpg" alt="Video preview image">
      </picture>
    </div>
    <div>
      <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">https://www.youtube.com/watch?v=dQw4w9WgXcQ</a>
    </div>
  </div>
</div>

Why this works:

• ✅ Authors just paste image and URL in sequence
• ✅ Pattern detection creates the embed block
• ✅ Image immediately preceding YouTube URL becomes the preview/poster image
• ✅ If no image, block still works with just the URL
• ✅ Minimal author effort
• ✅ Consistent behavior

When NOT to Use Auto-Blocked

Auto-blocking requires:

• Predictable, detectable patterns
• Implementation of auto-blocking logic in scripts.js
• Patterns that are truly common and repeatable

Don't create auto-blocking for:

• One-off special cases
• Complex patterns that are hard to detect reliably
• Cases where explicit blocks would be clearer

---

Choosing the Right Model

Content modeling is an art, not a science. There are often multiple valid approaches, and the "right" model depends on context, authoring needs, and implementation constraints.

Review the detailed examples above for each canonical model to understand their characteristics, strengths, and when they're most appropriate. Pay special attention to the "Why this works" and "Why this fails" explanations.

Key considerations:

• Standalone is the most flexible and often a safe default choice
• Collection works well when you have clear repeating items
• Configuration is frequently overused - only use for truly dynamic, API-driven content
• Auto-Blocked requires careful pattern design but can be worth it to make authors' lives easier

When in doubt, start with Standalone or Collection - they're simpler and more author-friendly than Configuration or Auto-Blocked.

Common Mistakes

Using Configuration when Standalone/Collection would work:

❌ BAD (unnecessary config)
| Card |
|------|
| image | hero.jpg |
| title | Welcome |

✅ GOOD (Standalone)
| Card |
|------|
| ![Welcome](hero.jpg) |
| **Welcome** |

Using Standalone when Collection would work:

❌ BAD (repeating standalone pattern)
Multiple separate blocks for each card

✅ GOOD (Collection)
| Cards |
|-------|
| ![Card 1](img1.jpg) | **Title 1** |
| ![Card 2](img2.jpg) | **Title 2** |

Over-engineering Auto-Blocked:

❌ BAD (complex pattern for rare use case)
Auto-detecting "testimonial quotes" by looking for:
- Italic paragraphs
- Followed by bold text
- In specific section types
Only appears 2-3 times on entire site, not worth the complexity

✅ GOOD (explicit block for clarity)
| Blockquote |
|------------|
| This product changed how we work. Absolutely essential. |
| *Sarah Johnson, CEO* |

Simple, clear, and easy for authors to create when needed

Summary

• Standalone: Unique elements, flexible structure
• Collection: Repeating items, rows = items, columns = parts
• Configuration: Dynamic behavior only, not static content
• Auto-Blocked: Common patterns, "magical" authoring

When in doubt, prefer simpler models (Standalone or Collection) over complex ones (Configuration or Auto-Blocked).