content-modeling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Content Modeling for AEM Edge Delivery Blocks

AEM Edge Delivery 区块的内容建模

This skill guides you through designing content models for AEM Edge Delivery Services blocks. A content model defines the table structure that authors work with when creating content

本技能将指导你为AEM Edge Delivery Services区块设计内容模型。内容模型定义了内容作者创建内容时使用的表格结构。

Related Skills

When to Use This Skill

何时使用本技能

✅ Use this skill when:

Creating new blocks (usually invoked by CDD at Step 3)
Modifying existing blocks in ways that change author-facing structure
Reviewing content models for best practices conformance
User explicitly asks about content modeling

❌ Skip this skill when:

Block already has a well-defined content model
You're only changing decoration code or styles (not structure)
Making minor tweaks that don't affect what authors create

✅ 建议使用本技能的场景：

创建新区块（通常由CDD在第3步调用）
修改现有区块且会改变面向内容作者的结构
审查内容模型是否符合最佳实践
用户明确询问内容建模相关问题

❌ 建议跳过本技能的场景：

区块已有定义完善的内容模型
仅修改装饰代码或样式（不涉及结构变更）
进行不影响内容作者创作的细微调整

Content Modeling Checklist

内容建模检查清单

Track your progress through content model design:

Step 1: Understand content requirements. See "Step 1: Understand Content Requirements" below
Step 2: Design block structure. See "Step 2: Design Block Structure" below
Step 3: Validate against best practices. See "Step 3: Validate Against Best Practices" below
Step 4: Document and return content model. See "Step 4: Document and Return" below

跟踪内容模型设计的进度：

步骤1：理解内容需求。详见下方“步骤1：理解内容需求”
步骤2：设计区块结构。详见下方“步骤2：设计区块结构”
步骤3：验证是否符合最佳实践。详见下方“步骤3：验证是否符合最佳实践”
步骤4：记录并交付内容模型。详见下方“步骤4：记录并交付”

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

优质的内容模型具备以下特点：

语义化：结构自身承载含义，无需依赖装饰
可预测：内容作者、开发人员和Agent都能清晰预期结构
可复用：可在不同创作界面和项目中通用

Step 1: Understand Content Requirements

步骤1：理解内容需求

Before designing a content model, understand what the block needs to accomplish and what content it requires.

Ask these questions:

What is the block's purpose? What problem does it solve for users?
What content elements are needed? (images, text, headings, links, etc.)
What is the visual layout? How should content be arranged on the page?
Is this content unique or repeating? One hero, or multiple cards?
Where does the content come from? Authored by users, or fetched from an API?
How complex is the authoring experience? Can authors create this easily, or does it need simplification?

Use canonical models as reference patterns:

AEM Edge Delivery has 4 canonical block models that serve as proven patterns:

Model	Best For	Examples
Standalone	Unique visual elements, one-off structures	Hero, Blockquote
Collection	Repeating semi-structured items	Cards, Carousel
Configuration	API-driven content ONLY (not static content)	Blog Listing, Search Results
Auto-Blocked	Simplify complex authoring, pattern detection	Tabs, YouTube Embed

Use these patterns to inform your design in Step 2, but focus first on understanding the content requirements.

Detailed resources:

Read
```
resources/canonical-models.md
```
for detailed examples and guidance on the 4 canonical models
If your content model is particularly complex or combines multiple models, see
```
resources/advanced-scenarios.md
```

在设计内容模型前，需明确区块的目标和所需内容。

可询问以下问题：

区块的用途是什么？ 它为用户解决什么问题？
需要哪些内容元素？（图片、文本、标题、链接等）
视觉布局是怎样的？ 内容应如何在页面上排列？
内容是唯一的还是重复的？ 单个英雄区块，还是多个卡片？
内容来源是什么？ 由用户创作，还是从API获取？
创作体验的复杂度如何？ 内容作者能否轻松创建，还是需要简化？

参考标准模型：

AEM Edge Delivery提供4种标准区块模型，均为经过验证的模式：

模型类型	适用场景	示例
Standalone	独特视觉元素、一次性结构	英雄区块（Hero）、引用区块（Blockquote）
Collection	重复的半结构化内容项	卡片（Cards）、轮播图（Carousel）
Configuration	仅适用于API驱动的内容（非静态内容）	博客列表（Blog Listing）、搜索结果（Search Results）
Auto-Blocked	简化复杂创作、模式识别	标签页（Tabs）、YouTube嵌入（YouTube Embed）

在步骤2的设计中可参考这些模式，但首先需聚焦于理解内容需求。

详细资源：

阅读
```
resources/canonical-models.md
```
获取4种标准模型的详细示例和指导
若内容模型特别复杂或融合多种模型，可查看
```
resources/advanced-scenarios.md
```

Step 2: Design Block Structure

步骤2：设计区块结构

Design the structure your block will follow in a document, using these key guidelines:

Essential rules:

Maximum 4 cells per row
Use semantic formatting (headings, bold, italic) to define meaning
Prefer block variants over config cells (use
```
| Hero (Dark) |
```
not
```
| style | dark |
```
)
Infer from context and use smart defaults to minimize author input
Be flexible with input structure - your decoration code can handle variations

Common patterns to reference:

These patterns align with the canonical models and can inform your design:

Standalone blocks: Use rows/columns as needed for unique structures. Be flexible about how authors organize content. Example: Hero where image and text can be in separate rows, columns, or combined.
Collection blocks: Each row = one item, columns = parts of each item. Keep columns consistent. Example: Cards with columns for [image] [heading, description, CTA].
Configuration blocks: Two-column key/value pairs for settings. Keep minimal - only true behavioral settings. Example: Blog Listing with
```
limit | 10
```
,
```
sort | date-desc
```
.
Auto-Blocked content: Design for simplest possible authoring. Often uses sections and section metadata. Example: Tabs auto-blocked from sections with H2 headings.

Detailed resources:

Read
```
resources/canonical-models.md
```
for examples of good vs. bad block structures
If dealing with complex scenarios (nested blocks, lists, forms), see
```
resources/advanced-scenarios.md
```

按照以下关键指南，设计区块在文档中遵循的结构：

核心规则：

每行最多4个单元格
使用语义化格式（标题、粗体、斜体）定义含义
优先使用区块变体而非配置单元格（使用
```
| Hero (Dark) |
```
而非
```
| style | dark |
```
）
结合上下文推断并使用智能默认值，减少内容作者的输入
对输入结构保持灵活——装饰代码可处理不同的输入变体

可参考的常见模式：

这些模式与标准模型一致，可为设计提供参考：

Standalone区块：根据独特结构需求使用行/列。对内容作者组织内容的方式保持灵活。示例：英雄区块的图片和文本可分开展示在不同行、列，或合并展示。
Collection区块：每行代表一个内容项，每列代表内容项的组成部分。保持列的一致性。示例：卡片区块包含[图片] [标题、描述、CTA]列。
Configuration区块：使用两列的键/值对配置设置。尽量精简——仅保留真正的行为设置。示例：博客列表配置
```
limit | 10
```
、
```
sort | date-desc
```
。
Auto-Blocked内容：为最简单的创作体验设计。通常使用章节和章节元数据。示例：从带有H2标题的章节自动生成标签页（Tabs）。

详细资源：

阅读
```
resources/canonical-models.md
```
查看优质与劣质区块结构的示例
若处理复杂场景（嵌套区块、列表、表单），可查看
```
resources/advanced-scenarios.md
```

Step 3: Validate Against Best Practices

步骤3：验证是否符合最佳实践

Step 4: Document and Return

步骤4：记录并交付

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

markdown

undefined

按照以下格式，将内容模型返回给调用技能（或用户）：

markdown

undefined

Content Model: [Block Name]

Content Model: [区块名称]

Block Structure

区块结构

Block Name
[Cell description]
[Cell description]

区块名称
[单元格说明]
[单元格说明]

How It Works

工作原理

[Explain what authors create and how the block 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., "h2 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. After documenting the model, return this to the calling skill (content-driven-development or building-blocks), which will handle what to do next, such as creating test content or implementing the block.

[重要的创作指南]
[语义化格式示例（如：“h2代表标题”）]
[结构的灵活性（如：“内容可放在单个单元格或拆分到两个单元格中”）]
[适用的常见变体（如有）]


**注意：** 本技能专注于设计内容模型。完成模型记录后，需将其返回给调用技能（content-driven-development或building-blocks），由该技能处理后续工作，例如创建测试内容或实现区块。

Resources

资源

resources/canonical-models.md

resources/canonical-models.md

Detailed guide to the 4 canonical block models (Standalone, Collection, Configuration, Auto-Blocked) with comprehensive examples showing both good and bad implementations. Includes "why this works" and "why this fails" explanations for each pattern, multiple variations, and anti-patterns to avoid.

4种标准区块模型（Standalone、Collection、Configuration、Auto-Blocked）的详细指南，包含全面的示例展示优质与劣质实现。每种模式均包含“为何可行”和“为何失效”的解释、多种变体，以及需避免的反模式。

resources/advanced-scenarios.md

resources/advanced-scenarios.md

Solutions for complex content modeling challenges including nested blocks, item-level configurations in collections, handling lists (with important guidance on not requiring authors to create lists), and form patterns.

针对复杂内容建模挑战的解决方案，包括嵌套区块、Collection中的内容项级配置、列表处理（包含重要的指导：不要求内容作者手动创建列表）以及表单模式。

Key Principles Revisited

核心原则回顾

When in doubt, remember:

Understand content requirements first - What does the block need to accomplish? What content elements are required? This understanding drives everything else.
Use canonical models as reference patterns - The 4 canonical models (Standalone, Collection, Configuration, Auto-Blocked) are proven patterns to inform your design, not rigid templates to follow.
Keep it simple - Authors should understand the structure intuitively. If it feels complex to explain, it's probably too complex to author.
Use semantic formatting - Let the structure carry meaning through headings, bold, italic, etc. - not through cell positions or complex configurations.
Be flexible - Your decoration code can handle variations in author input. Don't force authors into rigid structures for developer convenience.
Validate against best practices - Check your design against guidelines (4 cells per row, avoid spreadsheet-like structures, etc.) to inform a better design and surface potential concerns.

Content models are the foundation of author experience. Invest time in understanding requirements and designing thoughtful structures.

如有疑问，请牢记：

先理解内容需求 - 区块的目标是什么？需要哪些内容元素？这一认知将指导后续所有工作。
参考标准模型 - 4种标准模型（Standalone、Collection、Configuration、Auto-Blocked）是经过验证的设计参考模式，而非必须严格遵循的模板。
保持简洁 - 内容作者应能直观理解结构。如果难以解释，说明其对内容作者而言可能过于复杂。
使用语义化格式 - 通过标题、粗体、斜体等让结构承载含义，而非依赖单元格位置或复杂配置。
保持灵活 - 装饰代码可处理内容作者输入的变体。不要为了开发便利而强制内容作者使用僵化的结构。
验证是否符合最佳实践 - 根据指南（每行4个单元格、避免类似电子表格的结构等）检查设计，优化设计并发现潜在问题。

内容模型是内容作者体验的基础。请投入时间理解需求，设计贴心的结构。