Back to Details

html-to-generateblocks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HTML to GenerateBlocks V2 Conversion

将HTML转换为GenerateBlocks V2格式

Convert HTML/CSS layouts to GenerateBlocks V2 format using inline styles in block attributes.
使用区块属性中的内联样式，将HTML/CSS布局转换为GenerateBlocks V2格式。

Output Requirements

输出要求

ALWAYS output converted blocks to a file, never inline in the chat.
  • Output filename: 
    {original-name}-converted.html
    (e.g., 
    hero-converted.html
    )
  • For large conversions: Split into multiple files by section
  • Include a brief summary in chat describing what was converted
Why file output?
  • Converted block code is often 100+ lines
  • Easier to copy/paste into WordPress
  • Prevents truncation and formatting issues
  • Allows side-by-side comparison with original
始终将转换后的区块输出到文件中，绝不要直接在聊天中内联显示。
  • 输出文件名：
    {original-name}-converted.html
    （例如：
    hero-converted.html
    ）
  • 对于大型转换任务：按章节拆分为多个文件
  • 在聊天中包含一段简短的摘要，说明转换的内容
为什么要输出到文件？
  • 转换后的区块代码通常超过100行
  • 更易于复制粘贴到WordPress中
  • 避免截断和格式问题
  • 允许与原始内容进行并排比较

Core Principle

核心原则

Use both 
styles
and 
css
attributes:
  • styles
    : Basic properties (padding, margin, colors, display, flex, grid). Supports responsive keys like 
    "@media (max-width:1024px)":{...}
  • css
    : Base styles only (alphabetically sorted). Exceptions that go in 
    css
    : pseudo-elements (::before/::after), media queries, animations, parent hover targeting children
The 
css
attribute must NOT contain hover states or transitions - the plugin generates those from the 
styles
object.
Never use BEM or custom classes - all styling goes in block attributes.
同时使用
styles
和
css
属性：
  • styles
    ：基础属性（内边距、外边距、颜色、显示方式、弹性布局、网格布局）。支持响应式键值，例如
    "@media (max-width:1024px)":{...}
  • css
    ：仅包含基础样式（按字母顺序排序）。例外情况需放入
    css
    ：伪元素（::before/::after）、媒体查询、动画、父元素悬停触发子元素样式
css
属性中绝对不能包含悬停状态或过渡效果 - 插件会从
styles
对象自动生成这些样式。
绝不使用BEM命名法或自定义类 - 所有样式都要放入区块属性中。

When to Use Core Blocks

何时使用核心区块

For HTML elements not available in GenerateBlocks, use WordPress Core Blocks:
HTML ElementConvert ToReason
<video>
core/video
Native player controls, autoplay, loop
<audio>
core/audio
Native audio player
<iframe>
(YouTube, Vimeo)
core/embed
oEmbed support, responsive sizing
<table>
core/table
Semantic table structure
<figure>
with 
<figcaption>
core/image
Built-in caption support
<blockquote>
with cite
core/quote
Semantic quote with citation
<pre>
/ 
<code>
core/code
Preformatted code display
<ul>
/ 
<ol>
(semantic lists)
core/list
Use with 
.list
class
<hr>
core/separator
Horizontal rule
Gallery layouts
core/gallery
Lightbox, columns, captions
Background image sections
core/cover
Parallax, overlay, focal point
Text with emojis
core/paragraph
GenerateBlocks doesn't render emojis properly
Conversion rule: Use GenerateBlocks for layout containers and styled text. Use Core Blocks for specialized content types that have built-in functionality (players, embeds, tables, etc.).
对于GenerateBlocks中没有的HTML元素，请使用WordPress核心区块：
HTML元素转换为原因
<video>
core/video
原生播放器控制、自动播放、循环播放
<audio>
core/audio
原生音频播放器
<iframe>
（YouTube、Vimeo）
core/embed
支持oEmbed、响应式尺寸
<table>
core/table
语义化表格结构
包含
<figcaption>
的
<figure>
core/image
内置标题支持
包含cite的
<blockquote>
core/quote
带引用的语义化引用块
<pre>
/ 
<code>
core/code
预格式化代码显示
<ul>
/ 
<ol>
（语义化列表）
core/list
配合
.list
类使用
<hr>
core/separator
水平分隔线
画廊布局
core/gallery
灯箱、列布局、标题
背景图片区块
core/cover
视差效果、遮罩、焦点定位
带表情符号的文本
core/paragraph
GenerateBlocks无法正确渲染表情符号
转换规则： 使用GenerateBlocks处理布局容器和样式化文本。对于具备内置功能的特殊内容类型（播放器、嵌入内容、表格等），使用核心区块。

CRITICAL: htmlAttributes Format

关键注意事项：htmlAttributes格式

htmlAttributes MUST be an array of objects, NOT a plain object:
json
// ✅ CORRECT - Array of objects
"htmlAttributes": [
  {"attribute": "href", "value": "/contact/"},
  {"attribute": "target", "value": "_blank"},
  {"attribute": "id", "value": "section-id"}
]

// ❌ WRONG - Plain object (causes block editor recovery errors)
"htmlAttributes": {"href": "/contact/", "target": "_blank"}
linkHtmlAttributes (for media blocks) uses the same array format:
json
"linkHtmlAttributes": [
  {"attribute": "href", "value": "/product/"},
  {"attribute": "target", "value": "_blank"}
]
htmlAttributes必须是对象数组，不能是普通对象：
json
// ✅ 正确 - 对象数组
"htmlAttributes": [
  {"attribute": "href", "value": "/contact/"},
  {"attribute": "target", "value": "_blank"},
  {"attribute": "id", "value": "section-id"}
]

// ❌ 错误 - 普通对象（会导致区块编辑器恢复错误）
"htmlAttributes": {"href": "/contact/", "target": "_blank"}
linkHtmlAttributes（用于媒体区块）使用相同的数组格式：
json
"linkHtmlAttributes": [
  {"attribute": "href", "value": "/product/"},
  {"attribute": "target", "value": "_blank"}
]

Block Structure

区块结构

Standard Element Block

标准元素区块

Element blocks add 
"className":"gb-element"
to attributes. HTML class order: 
gb-element-{id} gb-element
:
html
<!-- wp:generateblocks/element {"uniqueId":"elem001","tagName":"div","styles":{"display":"flex","gap":"1rem","padding":"2rem"},"css":".gb-element-elem001{display:flex;gap:1rem;padding:2rem}@media(max-width:768px){.gb-element-elem001{flex-direction:column}}","className":"gb-element"} -->
<div class="gb-element-elem001 gb-element">
    <!-- Inner content -->
</div>
<!-- /wp:generateblocks/element -->
元素区块需在属性中添加
"className":"gb-element"
。HTML类顺序：
gb-element-{id} gb-element
：
html
<!-- wp:generateblocks/element {"uniqueId":"elem001","tagName":"div","styles":{"display":"flex","gap":"1rem","padding":"2rem"},"css":".gb-element-elem001{display:flex;gap:1rem;padding:2rem}@media(max-width:768px){.gb-element-elem001{flex-direction:column}}","className":"gb-element"} -->
<div class="gb-element-elem001 gb-element">
    <!-- 内部内容 -->
</div>
<!-- /wp:generateblocks/element -->

Text Block (for headings, paragraphs, links)

文本区块（用于标题、段落、链接）

html
<!-- wp:generateblocks/text {"uniqueId":"text001","tagName":"h2","styles":{"fontSize":"2rem","fontWeight":"900","color":"#0a0a0a"},"css":".gb-text-text001{font-size:2rem;font-weight:900;color:#0a0a0a}"} -->
<h2 class="gb-text gb-text-text001">Heading Text</h2>
<!-- /wp:generateblocks/text -->
html
<!-- wp:generateblocks/text {"uniqueId":"text001","tagName":"h2","styles":{"fontSize":"2rem","fontWeight":"900","color":"#0a0a0a"},"css":".gb-text-text001{font-size:2rem;font-weight:900;color:#0a0a0a}"} -->
<h2 class="gb-text gb-text-text001">标题文本</h2>
<!-- /wp:generateblocks/text -->

Link as Card Wrapper

作为卡片容器的链接

Cards with inner blocks use 
generateblocks/element
(not 
text
) with 
tagName: "a"
:
html
<!-- wp:generateblocks/element {"uniqueId":"card001","tagName":"a","htmlAttributes":[{"attribute":"href","value":"/services/"}],"styles":{"backgroundColor":"white","borderRadius":"1rem","display":"flex","flexDirection":"column","padding":"2rem","textDecoration":"none"},"css":".gb-element-card001{background-color:white;border-radius:1rem;display:flex;flex-direction:column;padding:2rem;text-decoration:none}","className":"gb-element"} -->
<a class="gb-element-card001 gb-element" href="/services/">
    <!-- Inner blocks (text, media, shape) -->
</a>
<!-- /wp:generateblocks/element -->
Plain text links (no inner blocks) use 
generateblocks/text
with 
tagName: "a"
— no 
htmlAttributes
for href:
html
<!-- wp:generateblocks/text {"uniqueId":"link001","tagName":"a","styles":{"color":"#c0392b","fontSize":"0.9375rem","fontWeight":"600","textDecoration":"none"},"css":".gb-text-link001{color:#c0392b;font-size:0.9375rem;font-weight:600;text-decoration:none}"} -->
<a class="gb-text gb-text-link001">Learn more</a>
<!-- /wp:generateblocks/text -->
包含内部区块的卡片需使用
generateblocks/element
（而非
text
），并设置
tagName: "a"
：
html
<!-- wp:generateblocks/element {"uniqueId":"card001","tagName":"a","htmlAttributes":[{"attribute":"href","value":"/services/"}],"styles":{"backgroundColor":"white","borderRadius":"1rem","display":"flex","flexDirection":"column","padding":"2rem","textDecoration":"none"},"css":".gb-element-card001{background-color:white;border-radius:1rem;display:flex;flex-direction:column;padding:2rem;text-decoration:none}","className":"gb-element"} -->
<a class="gb-element-card001 gb-element" href="/services/">
    <!-- 内部区块（文本、媒体、形状） -->
</a>
<!-- /wp:generateblocks/element -->
纯文本链接（无内部区块）使用
generateblocks/text
并设置
tagName: "a"
—— 无需为href设置
htmlAttributes
：
html
<!-- wp:generateblocks/text {"uniqueId":"link001","tagName":"a","styles":{"color":"#c0392b","fontSize":"0.9375rem","fontWeight":"600","textDecoration":"none"},"css":".gb-text-link001{color:#c0392b;font-size:0.9375rem;font-weight:600;text-decoration:none}"} -->
<a class="gb-text gb-text-link001">了解更多</a>
<!-- /wp:generateblocks/text -->

Media/Image Block

媒体/图片区块

html
<!-- wp:generateblocks/media {"uniqueId":"img001","mediaType":"image","htmlAttributes":[{"attribute":"src","value":"https://example.com/image.jpg"},{"attribute":"alt","value":"Description"},{"attribute":"loading","value":"lazy"},{"attribute":"width","value":"600"},{"attribute":"height","value":"400"}],"styles":{"display":"block","width":"100%"},"css":".gb-media-img001{display:block;width:100%}"} -->
<img class="gb-media gb-media-img001" src="https://example.com/image.jpg" alt="Description" loading="lazy" width="600" height="400" />
<!-- /wp:generateblocks/media -->
html
<!-- wp:generateblocks/media {"uniqueId":"img001","mediaType":"image","htmlAttributes":[{"attribute":"src","value":"https://example.com/image.jpg"},{"attribute":"alt","value":"描述"},{"attribute":"loading","value":"lazy"},{"attribute":"width","value":"600"},{"attribute":"height","value":"400"}],"styles":{"display":"block","width":"100%"},"css":".gb-media-img001{display:block;width:100%}"} -->
<img class="gb-media gb-media-img001" src="https://example.com/image.jpg" alt="描述" loading="lazy" width="600" height="400" />
<!-- /wp:generateblocks/media -->

Text 
<a>
vs Element 
<a>
Links

文本
<a>
与元素
<a>
链接的区别

Block Type
htmlAttributes
for href
href
in HTML		Use Case
generateblocks/text
with 
tagName: "a"
No - plugin manages link internallyNoPlain text buttons/links (no inner blocks)
generateblocks/element
with 
tagName: "a"
Yes - 
[{"attribute":"href","value":"/url/"}]
YesContainers wrapping inner blocks (cards, icon buttons)
Rule: Text 
<a>
blocks are leaf blocks - the link URL is managed by the editor UI. Element 
<a>
blocks are containers - they need explicit 
htmlAttributes
for the href.
Buttons with icons use 
generateblocks/element
(tagName 
a
) wrapping 
generateblocks/text
+ 
generateblocks/shape
blocks. Plain text buttons use 
generateblocks/text
.
区块类型href是否使用
htmlAttributes
HTML中是否包含
href
使用场景
设置
tagName: "a"
的
generateblocks/text
否 - 插件内部管理链接否纯文本按钮/链接（无内部区块）
设置
tagName: "a"
的
generateblocks/element
是 - 使用
[{"attribute":"href","value":"/url/"}]
是包裹内部区块的容器（卡片、图标按钮）
规则： 文本
<a>
区块是叶子区块 - 链接URL由编辑器界面管理。元素
<a>
区块是容器 - 需要显式设置
htmlAttributes
来定义href。
带图标的按钮使用
generateblocks/element
（tagName为
a
）包裹
generateblocks/text
+ 
generateblocks/shape
区块。纯文本按钮使用
generateblocks/text
。

Styles vs CSS Decision Matrix

Styles与CSS决策矩阵

FeatureUse 
styles
Use 
css
Layout (display, flex, grid)✅Also in CSS (base styles)
Spacing (padding, margin, gap)✅Also in CSS (base styles)
Colors (background, text)✅Also in CSS (base styles)
Typography (font-size, weight)✅Also in CSS (base styles)
Basic borders, border-radius✅Also in CSS (base styles)
Responsive overrides✅ 
"@media (max-width:1024px)":{...}
Also in CSS
Hover states✅ via 
styles
object		❌ Never in 
css
 (plugin generates)
Transitions✅ via 
styles
object		❌ Never in 
css
 (plugin generates)
Pseudo-elements (::before/::after)❌✅ Only CSS
Media queries✅ (simple overrides)✅ (complex rules)
Animations (@keyframes)❌✅ Only CSS
Parent hover targeting children❌✅ Only CSS (in child's 
css
)
Pattern: Put base properties in both 
styles
and 
css
(alphabetically sorted). The 
css
attribute contains base styles plus exceptions (pseudo-elements, media queries, animations, parent-hover-child selectors). Never put hover states or transitions in 
css
.
特性使用
styles
使用
css
布局（display、flex、grid）✅同时在CSS中包含（基础样式）
间距（padding、margin、gap）✅同时在CSS中包含（基础样式）
颜色（背景色、文本色）✅同时在CSS中包含（基础样式）
排版（font-size、font-weight）✅同时在CSS中包含（基础样式）
基础边框、圆角✅同时在CSS中包含（基础样式）
响应式覆盖✅ 使用
"@media (max-width:1024px)":{...}
同时在CSS中包含
悬停状态✅ 通过
styles
对象		❌ 绝不放入
css
（由插件生成）
过渡效果✅ 通过
styles
对象		❌ 绝不放入
css
（由插件生成）
伪元素（::before/::after）❌✅ 仅放入CSS
媒体查询✅（简单覆盖）✅（复杂规则）
动画（@keyframes）❌✅ 仅放入CSS
父元素悬停触发子元素样式❌✅ 仅放入CSS（在子元素的
css
中）
模式： 将基础属性同时放入
styles
和
css
（按字母顺序排序）。
css
属性包含基础样式以及例外情况（伪元素、媒体查询、动画、父元素悬停触发子元素选择器）。绝不要将悬停状态或过渡效果放入
css
中。

Common Patterns

常见模式

Card with Animated Underline

带动画下划线的卡片

Cards with inner blocks use 
generateblocks/element
. Pseudo-elements (::after) and parent-hover-pseudo go in 
css
. Hover states and transitions do NOT go in 
css
.
html
<!-- wp:generateblocks/element {"uniqueId":"card001","tagName":"a","htmlAttributes":[{"attribute":"href","value":"/link/"}],"styles":{"backgroundColor":"white","border":"1px solid transparent","borderRadius":"1rem","display":"flex","flexDirection":"column","padding":"2rem","position":"relative","textDecoration":"none"},"css":".gb-element-card001{background-color:white;border:1px solid transparent;border-radius:1rem;display:flex;flex-direction:column;padding:2rem;position:relative;text-decoration:none}.gb-element-card001::after{background:#c0392b;bottom:0;content:'';height:3px;left:0;position:absolute;transform:scaleX(0);transform-origin:left;transition:transform 0.4s cubic-bezier(0.16, 1, 0.3, 1);width:100%}.gb-element-card001:hover::after{transform:scaleX(1)}","className":"gb-element"} -->
<a class="gb-element-card001 gb-element" href="/link/">
    <!-- Inner blocks -->
</a>
<!-- /wp:generateblocks/element -->
包含内部区块的卡片使用
generateblocks/element
。伪元素（::after）和父元素悬停触发伪元素的样式放入
css
。悬停状态和过渡效果绝不放入
css
。
html
<!-- wp:generateblocks/element {"uniqueId":"card001","tagName":"a","htmlAttributes":[{"attribute":"href","value":"/link/"}],"styles":{"backgroundColor":"white","border":"1px solid transparent","borderRadius":"1rem","display":"flex","flexDirection":"column","padding":"2rem","position":"relative","textDecoration":"none"},"css":".gb-element-card001{background-color:white;border:1px solid transparent;border-radius:1rem;display:flex;flex-direction:column;padding:2rem;position:relative;text-decoration:none}.gb-element-card001::after{background:#c0392b;bottom:0;content:'';height:3px;left:0;position:absolute;transform:scaleX(0);transform-origin:left;transition:transform 0.4s cubic-bezier(0.16, 1, 0.3, 1);width:100%}.gb-element-card001:hover::after{transform:scaleX(1)}","className":"gb-element"} -->
<a class="gb-element-card001 gb-element" href="/link/">
    <!-- 内部区块 -->
</a>
<!-- /wp:generateblocks/element -->

Grid Layout (Responsive)

响应式网格布局

html
<!-- wp:generateblocks/element {"uniqueId":"grid001","tagName":"div","styles":{"display":"grid","gridTemplateColumns":"repeat(4, minmax(0, 1fr))","gap":"1rem"},"css":".gb-element-grid001{display:grid;grid-template-columns:repeat(4, minmax(0, 1fr));gap:1rem}@media(max-width:1024px){.gb-element-grid001{grid-template-columns:repeat(2, minmax(0, 1fr))!important}}@media(max-width:768px){.gb-element-grid001{grid-template-columns:1fr!important}}"} -->
<div class="gb-element gb-element-grid001">
    <!-- Grid items -->
</div>
<!-- /wp:generateblocks/element -->
html
<!-- wp:generateblocks/element {"uniqueId":"grid001","tagName":"div","styles":{"display":"grid","gridTemplateColumns":"repeat(4, minmax(0, 1fr))","gap":"1rem"},"css":".gb-element-grid001{display:grid;grid-template-columns:repeat(4, minmax(0, 1fr));gap:1rem}@media(max-width:1024px){.gb-element-grid001{grid-template-columns:repeat(2, minmax(0, 1fr))!important}}@media(max-width:768px){.gb-element-grid001{grid-template-columns:1fr!important}}"} -->
<div class="gb-element gb-element-grid001">
    <!-- 网格项 -->
</div>
<!-- /wp:generateblocks/element -->

Icon (Shape Block with SVG)

图标（带SVG的形状区块）

SVG icons use 
generateblocks/shape
. Two valid approaches:
Approach 1: 
styles.svg
object (plugin generates 
.gb-shape-{id} svg{...}
CSS):
html
<!-- wp:generateblocks/shape {"uniqueId":"icon001","styles":{"alignItems":"center","backgroundColor":"#f5f5f3","borderRadius":"1rem","color":"#c0392b","display":"flex","height":"3.5rem","justifyContent":"center","width":"3.5rem","svg":{"fill":"none","height":"1.5rem","stroke":"currentColor","width":"1.5rem"}},"css":".gb-shape-icon001{align-items:center;background-color:#f5f5f3;border-radius:1rem;color:#c0392b;display:flex;height:3.5rem;justify-content:center;width:3.5rem}.gb-shape-icon001 svg{fill:none;height:1.5rem;stroke:currentColor;width:1.5rem}.gb-element-card001:hover .gb-shape-icon001{background-color:#c0392b;color:white;transform:scale(1.05) rotate(-3deg)}"} -->
<span class="gb-shape gb-shape-icon001"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M13 2 3 14h9l-1 8 10-12h-9l1-8z"/></svg></span>
<!-- /wp:generateblocks/shape -->
Approach 2: Simple styles (for quick inline icons):
html
<!-- wp:generateblocks/shape {"uniqueId":"check001","styles":{"color":"#10b981","height":"20px","width":"20px"},"css":".gb-shape-check001{color:#10b981;height:20px;width:20px}"} -->
<span class="gb-shape gb-shape-check001"><svg stroke-linejoin="round" stroke-linecap="round" stroke-width="3" stroke="currentColor" fill="none" viewBox="0 0 24 24"><polyline points="20 6 9 17 4 12"></polyline></svg></span>
<!-- /wp:generateblocks/shape -->
Parent hover targeting icons is written in the shape block's 
css
(as shown in Approach 1).
SVG图标使用
generateblocks/shape
。有两种有效方式：
方式1：
styles.svg
对象（插件生成
.gb-shape-{id} svg{...}
CSS）：
html
<!-- wp:generateblocks/shape {"uniqueId":"icon001","styles":{"alignItems":"center","backgroundColor":"#f5f5f3","borderRadius":"1rem","color":"#c0392b","display":"flex","height":"3.5rem","justifyContent":"center","width":"3.5rem","svg":{"fill":"none","height":"1.5rem","stroke":"currentColor","width":"1.5rem"}},"css":".gb-shape-icon001{align-items:center;background-color:#f5f5f3;border-radius:1rem;color:#c0392b;display:flex;height:3.5rem;justify-content:center;width:3.5rem}.gb-shape-icon001 svg{fill:none;height:1.5rem;stroke:currentColor;width:1.5rem}.gb-element-card001:hover .gb-shape-icon001{background-color:#c0392b;color:white;transform:scale(1.05) rotate(-3deg)}"} -->
<span class="gb-shape gb-shape-icon001"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M13 2 3 14h9l-1 8 10-12h-9l1-8z"/></svg></span>
<!-- /wp:generateblocks/shape -->
方式2：简单样式（用于快速内联图标）：
html
<!-- wp:generateblocks/shape {"uniqueId":"check001","styles":{"color":"#10b981","height":"20px","width":"20px"},"css":".gb-shape-check001{color:#10b981;height:20px;width:20px}"} -->
<span class="gb-shape gb-shape-check001"><svg stroke-linejoin="round" stroke-linecap="round" stroke-width="3" stroke="currentColor" fill="none" viewBox="0 0 24 24"><polyline points="20 6 9 17 4 12"></polyline></svg></span>
<!-- /wp:generateblocks/shape -->
父元素悬停触发图标样式需写在形状区块的
css
中（如方式1所示）。

Featured Card (Dark, Span Multiple Columns)

特色卡片（深色、跨多列）

html
<!-- wp:generateblocks/element {"uniqueId":"feat001","tagName":"div","styles":{"background":"linear-gradient(135deg, #0a0a0a 0%, #1a1a1a 100%)","borderRadius":"1rem","display":"flex","flexDirection":"column","gap":"1rem","gridColumn":"span 2","gridRow":"span 2","minHeight":"26rem","padding":"2rem","position":"relative"},"css":".gb-element-feat001{background:linear-gradient(135deg, #0a0a0a 0%, #1a1a1a 100%);border-radius:1rem;display:flex;flex-direction:column;gap:1rem;grid-column:span 2;grid-row:span 2;min-height:26rem;padding:2rem;position:relative}.gb-element-feat001::before{background:radial-gradient(circle at 100% 0%, rgba(192, 57, 43, 0.2) 0%, transparent 60%);content:'';height:100%;pointer-events:none;position:absolute;right:0;top:0;width:60%}.gb-element-feat001>*{position:relative;z-index:1}@media(max-width:1024px){.gb-element-feat001{grid-column:span 2;grid-row:span 1;min-height:auto}}@media(max-width:768px){.gb-element-feat001{grid-column:span 1}}","className":"gb-element"} -->
<div class="gb-element-feat001 gb-element">
    <!-- Featured card content -->
</div>
<!-- /wp:generateblocks/element -->
html
<!-- wp:generateblocks/element {"uniqueId":"feat001","tagName":"div","styles":{"background":"linear-gradient(135deg, #0a0a0a 0%, #1a1a1a 100%)","borderRadius":"1rem","display":"flex","flexDirection":"column","gap":"1rem","gridColumn":"span 2","gridRow":"span 2","minHeight":"26rem","padding":"2rem","position":"relative"},"css":".gb-element-feat001{background:linear-gradient(135deg, #0a0a0a 0%, #1a1a1a 100%);border-radius:1rem;display:flex;flex-direction:column;gap:1rem;grid-column:span 2;grid-row:span 2;min-height:26rem;padding:2rem;position:relative}.gb-element-feat001::before{background:radial-gradient(circle at 100% 0%, rgba(192, 57, 43, 0.2) 0%, transparent 60%);content:'';height:100%;pointer-events:none;position:absolute;right:0;top:0;width:60%}.gb-element-feat001>*{position:relative;z-index:1}@media(max-width:1024px){.gb-element-feat001{grid-column:span 2;grid-row:span 1;min-height:auto}}@media(max-width:768px){.gb-element-feat001{grid-column:span 1}}","className":"gb-element"} -->
<div class="gb-element-feat001 gb-element">
    <!-- 特色卡片内容 -->
</div>
<!-- /wp:generateblocks/element -->

Badge (Absolute Position)

徽章（绝对定位）

html
<!-- wp:generateblocks/text {"uniqueId":"badge001","tagName":"span","styles":{"backgroundColor":"#c0392b","borderRadius":"2rem","color":"white","fontSize":"0.75rem","fontWeight":"600","letterSpacing":"0.05em","padding":"0.25rem 0.625rem","position":"absolute","right":"1rem","textTransform":"uppercase","top":"1rem"},"css":".gb-text-badge001{background-color:#c0392b;border-radius:2rem;color:white;font-size:0.75rem;font-weight:600;letter-spacing:0.05em;padding:0.25rem 0.625rem;position:absolute;right:1rem;text-transform:uppercase;top:1rem}"} -->
<span class="gb-text gb-text-badge001">Recommended</span>
<!-- /wp:generateblocks/text -->
html
<!-- wp:generateblocks/text {"uniqueId":"badge001","tagName":"span","styles":{"backgroundColor":"#c0392b","borderRadius":"2rem","color":"white","fontSize":"0.75rem","fontWeight":"600","letterSpacing":"0.05em","padding":"0.25rem 0.625rem","position":"absolute","right":"1rem","textTransform":"uppercase","top":"1rem"},"css":".gb-text-badge001{background-color:#c0392b;border-radius:2rem;color:white;font-size:0.75rem;font-weight:600;letter-spacing:0.05em;padding:0.25rem 0.625rem;position:absolute;right:1rem;text-transform:uppercase;top:1rem}"} -->
<span class="gb-text gb-text-badge001">推荐</span>
<!-- /wp:generateblocks/text -->

Dynamic Content with Query Blocks

带查询区块的动态内容

For sections with dynamic WordPress posts, use native query blocks with GenerateBlocks for styling:
html
<!-- wp:query {"queryId":1,"query":{"perPage":12,"postType":"post","order":"desc","orderBy":"date","taxQuery":{"category":{"terms":[],"operator":"NOT IN"}}}} -->
<div class="wp-block-query">
    <!-- wp:post-template {"style":{"spacing":{"blockGap":"1rem"}}} -->

        <!-- wp:generateblocks/element {"uniqueId":"post001","tagName":"a","styles":{"backgroundColor":"white","border":"1px solid #e5e5e5","borderRadius":"1rem","display":"flex","flexDirection":"column","overflow":"hidden","textDecoration":"none"},"css":".gb-element-post001{background-color:white;border:1px solid #e5e5e5;border-radius:1rem;display:flex;flex-direction:column;overflow:hidden;text-decoration:none}","className":"gb-element"} -->
        <a class="gb-element-post001 gb-element">
            <!-- wp:post-featured-image {"isLink":false,"aspectRatio":"12/5"} /-->

            <!-- wp:generateblocks/element {"uniqueId":"post002","tagName":"div","styles":{"display":"flex","flex":"1","flexDirection":"column","padding":"1rem"},"css":".gb-element-post002{display:flex;flex:1;flex-direction:column;padding:1rem}","className":"gb-element"} -->
            <div class="gb-element-post002 gb-element">
                <!-- wp:post-title {"isLink":false,"style":{"typography":{"fontSize":"1.125rem","fontWeight":"700"}}} /-->
                <!-- wp:post-excerpt {"excerptLength":14} /-->
            </div>
            <!-- /wp:generateblocks/element -->
        </a>
        <!-- /wp:generateblocks/element -->

    <!-- /wp:post-template -->
</div>
<!-- /wp:query -->
对于包含WordPress动态文章的区块，使用原生查询区块并配合GenerateBlocks进行样式设置：
html
<!-- wp:query {"queryId":1,"query":{"perPage":12,"postType":"post","order":"desc","orderBy":"date","taxQuery":{"category":{"terms":[],"operator":"NOT IN"}}}} -->
<div class="wp-block-query">
    <!-- wp:post-template {"style":{"spacing":{"blockGap":"1rem"}}} -->

        <!-- wp:generateblocks/element {"uniqueId":"post001","tagName":"a","styles":{"backgroundColor":"white","border":"1px solid #e5e5e5","borderRadius":"1rem","display":"flex","flexDirection":"column","overflow":"hidden","textDecoration":"none"},"css":".gb-element-post001{background-color:white;border:1px solid #e5e5e5;border-radius:1rem;display:flex;flex-direction:column;overflow:hidden;text-decoration:none}","className":"gb-element"} -->
        <a class="gb-element-post001 gb-element">
            <!-- wp:post-featured-image {"isLink":false,"aspectRatio":"12/5"} /-->

            <!-- wp:generateblocks/element {"uniqueId":"post002","tagName":"div","styles":{"display":"flex","flex":"1","flexDirection":"column","padding":"1rem"},"css":".gb-element-post002{display:flex;flex:1;flex-direction:column;padding:1rem}","className":"gb-element"} -->
            <div class="gb-element-post002 gb-element">
                <!-- wp:post-title {"isLink":false,"style":{"typography":{"fontSize":"1.125rem","fontWeight":"700"}}} /-->
                <!-- wp:post-excerpt {"excerptLength":14} /-->
            </div>
            <!-- /wp:generateblocks/element -->
        </a>
        <!-- /wp:generateblocks/element -->

    <!-- /wp:post-template -->
</div>
<!-- /wp:query -->

Unique ID Convention

唯一ID命名规范

  • Format: 
    {section}{number}{letter}
    (e.g., 
    hero001a
    , 
    serv023
    , 
    tool014
    )
  • Section prefix: 3-4 characters (hero, serv, tool, blog, feat)
  • Number: Sequential 001-999
  • Optional letter: For nested elements (a, b, c)
  • 格式：
    {section}{number}{letter}
    （例如：
    hero001a
    , 
    serv023
    , 
    tool014
    ）
  • 区块前缀：3-4个字符（hero, serv, tool, blog, feat）
  • 数字：001-999的连续序号
  • 可选字母：用于嵌套元素（a, b, c）

Conversion Workflow

转换流程

  1. Read original HTML/CSS - Understand structure and styles
  2. Identify sections - Break into logical components
  3. Map BEM classes to blocks - Each 
    .block__element
    becomes a GenerateBlocks element
  4. Extract base styles - Put in 
    styles
    attribute
  5. Extract complex styles - Put in 
    css
    attribute (pseudo-elements, media queries, parent-hover-child). Never put hover states or transitions in 
    css
  6. Create unique IDs - Follow convention
  7. Test responsive behavior - Ensure media queries work
  8. Handle dynamic content - Use WordPress query blocks
  1. 阅读原始HTML/CSS - 理解结构和样式
  2. 识别区块 - 拆分为逻辑组件
  3. 将BEM类映射到区块 - 每个
    .block__element
    转换为一个GenerateBlocks元素
  4. 提取基础样式 - 放入
    styles
    属性
  5. 提取复杂样式 - 放入
    css
    属性（伪元素、媒体查询、父元素悬停触发子元素样式）。绝不要将悬停状态或过渡效果放入
    css
  6. 创建唯一ID - 遵循命名规范
  7. 测试响应式行为 - 确保媒体查询正常工作
  8. 处理动态内容 - 使用WordPress查询区块

CSS Syntax Rules

CSS语法规则

In 
styles
attribute (JavaScript object):

在
styles
属性中（JavaScript对象）：

json
{
  "display": "flex",
  "flexDirection": "column",
  "backgroundColor": "#ffffff",
  "borderRadius": "1rem",
  "marginBottom": "2rem"
}
json
{
  "display": "flex",
  "flexDirection": "column",
  "backgroundColor": "#ffffff",
  "borderRadius": "1rem",
  "marginBottom": "2rem"
}

In 
css
attribute (CSS string):

在
css
属性中（CSS字符串）：

css
.gb-element-id{background-color:#ffffff;border-radius:1rem;display:flex;flex-direction:column;margin-bottom:2rem}@media(max-width:768px){.gb-element-id{flex-direction:row}}
Rules:
  • CSS must be minified (no line breaks, minimal spaces)
  • Properties must be alphabetically sorted
  • Contains base styles only — no hover states, no transitions
  • Exceptions: pseudo-elements (::before/::after), media queries, animations, parent hover targeting children
css
.gb-element-id{background-color:#ffffff;border-radius:1rem;display:flex;flex-direction:column;margin-bottom:2rem}@media(max-width:768px){.gb-element-id{flex-direction:row}}
规则：
  • CSS必须压缩（无换行，最少空格）
  • 属性必须按字母顺序排序
  • 仅包含基础样式 —— 无悬停状态，无过渡效果
  • 例外情况：伪元素（::before/::after）、媒体查询、动画、父元素悬停触发子元素样式

Responsive Patterns

响应式模式

Mobile-First Grid

移动端优先网格

css
.gb-element-grid{display:grid;grid-template-columns:1fr}@media(min-width:768px){.gb-element-grid{grid-template-columns:repeat(2, minmax(0, 1fr))}}@media(min-width:1024px){.gb-element-grid{grid-template-columns:repeat(4, minmax(0, 1fr))}}
css
.gb-element-grid{display:grid;grid-template-columns:1fr}@media(min-width:768px){.gb-element-grid{grid-template-columns:repeat(2, minmax(0, 1fr))}}@media(min-width:1024px){.gb-element-grid{grid-template-columns:repeat(4, minmax(0, 1fr))}}

Desktop-First Grid (Match Original)

桌面端优先网格（匹配原始设计）

css
.gb-element-grid{display:grid;grid-template-columns:repeat(4, minmax(0, 1fr));gap:1rem}@media(max-width:1024px){.gb-element-grid{grid-template-columns:repeat(2, minmax(0, 1fr))!important}}@media(max-width:768px){.gb-element-grid{grid-template-columns:1fr!important}}
css
.gb-element-grid{display:grid;grid-template-columns:repeat(4, minmax(0, 1fr));gap:1rem}@media(max-width:1024px){.gb-element-grid{grid-template-columns:repeat(2, minmax(0, 1fr))!important}}@media(max-width:768px){.gb-element-grid{grid-template-columns:1fr!important}}

Sticky Sidebar

粘性侧边栏

css
.gb-element-sidebar{position:sticky;top:calc(var(--header-height, 80px) + 1rem)}@media(max-width:1024px){.gb-element-sidebar{position:static}}
css
.gb-element-sidebar{position:sticky;top:calc(var(--header-height, 80px) + 1rem)}@media(max-width:1024px){.gb-element-sidebar{position:static}}

CRITICAL: No Extra HTML Comments

关键注意事项：禁止额外HTML注释

⛔ NEVER add HTML comments other than WordPress block markers.
The ONLY allowed comments are WordPress block delimiters:
  • <!-- wp:generateblocks/element {...} -->
    and 
    <!-- /wp:generateblocks/element -->
  • <!-- wp:generateblocks/text {...} -->
    and 
    <!-- /wp:generateblocks/text -->
  • <!-- wp:generateblocks/media {...} -->
    and 
    <!-- /wp:generateblocks/media -->
  • <!-- wp:generateblocks/shape {...} -->
    and 
    <!-- /wp:generateblocks/shape -->
  • <!-- wp:image {...} -->
    and 
    <!-- /wp:image -->
  • <!-- wp:video {...} -->
    and 
    <!-- /wp:video -->
  • <!-- wp:embed {...} -->
    and 
    <!-- /wp:embed -->
  • Any other 
    <!-- wp:{namespace}/{block} -->
    format
WRONG - These will break the block editor:
html
<!-- This is a card -->
<!-- Section header -->
<!-- Hero content goes here -->
<!-- Button wrapper -->
CORRECT - Only block delimiters:
html
<!-- wp:generateblocks/element {"uniqueId":"card001",...} -->
<div class="gb-element gb-element-card001">
    <!-- wp:image {"id":123} -->
    <figure class="wp-block-image"><img src="image.jpg" alt=""/></figure>
    <!-- /wp:image -->
</div>
<!-- /wp:generateblocks/element -->
Any extra HTML comments will break the WordPress block editor and cause parsing errors. This is non-negotiable. Do NOT add descriptive comments, section labels, or any other HTML comments.
⛔ 绝不要添加WordPress区块标记以外的HTML注释。
唯一允许的注释是WordPress区块分隔符：
  • <!-- wp:generateblocks/element {...} -->
    和 
    <!-- /wp:generateblocks/element -->
  • <!-- wp:generateblocks/text {...} -->
    和 
    <!-- /wp:generateblocks/text -->
  • <!-- wp:generateblocks/media {...} -->
    和 
    <!-- /wp:generateblocks/media -->
  • <!-- wp:generateblocks/shape {...} -->
    和 
    <!-- /wp:generateblocks/shape -->
  • <!-- wp:image {...} -->
    和 
    <!-- /wp:image -->
  • <!-- wp:video {...} -->
    和 
    <!-- /wp:video -->
  • <!-- wp:embed {...} -->
    和 
    <!-- /wp:embed -->
  • 任何其他
    <!-- wp:{namespace}/{block} -->
    格式
错误示例 - 这些会破坏区块编辑器：
html
<!-- 这是一个卡片 -->
<!-- 区块标题 -->
<!-- 英雄内容放在这里 -->
<!-- 按钮容器 -->
正确示例 - 仅包含区块分隔符：
html
<!-- wp:generateblocks/element {"uniqueId":"card001",...} -->
<div class="gb-element gb-element-card001">
    <!-- wp:image {"id":123} -->
    <figure class="wp-block-image"><img src="image.jpg" alt=""/></figure>
    <!-- /wp:image -->
</div>
<!-- /wp:generateblocks/element -->
任何额外的HTML注释都会破坏WordPress区块编辑器并导致解析错误。这是硬性要求，请勿添加描述性注释、区块标签或任何其他HTML注释。

Design Inference (When CSS Not Provided)

设计推断（当未提供CSS时）

When converting HTML without explicit CSS values, infer styles based on context:
GeneratePress Defaults:
  • Primary: 
    #0073e6
  • Text: 
    #222222
    , Muted: 
    #757575
  • Body: 
    17px
    , line-height 
    1.7
  • H1: 
    42px
    , H2: 
    35px
    , H3: 
    29px
  • Section padding: 
    60px
  • Container max-width: 
    var(--gb-container-width)
gauravtiwari.org Design System:
  • Primary: 
    #c0392b
  • Text: 
    #0a0a0a
    , Muted: 
    #5c5c5c
  • Background: 
    #ffffff
    , Light: 
    #f5f5f3
  • Headings: font-weight 
    900
    , letter-spacing 
    -0.03em
  • Section padding: 
    4rem
  • Card radius: 
    1rem
    , Button radius: 
    2rem
  • Hover lift: 
    translateY(-6px)
  • Shadow: 
    0 20px 60px rgba(0,0,0,0.15)
当转换无明确CSS值的HTML时，根据上下文推断样式：
GeneratePress默认值：
  • 主色调：
    #0073e6
  • 文本色：
    #222222
    ，次要文本色：
    #757575
  • 正文字号：
    17px
    ，行高
    1.7
  • H1：
    42px
    ，H2：
    35px
    ，H3：
    29px
  • 区块内边距：
    60px
  • 容器最大宽度：
    var(--gb-container-width)
gauravtiwari.org设计系统：
  • 主色调：
    #c0392b
  • 文本色：
    #0a0a0a
    ，次要文本色：
    #5c5c5c
  • 背景色：
    #ffffff
    ，浅色背景：
    #f5f5f3
  • 标题：字重
    900
    ，字母间距
    -0.03em
  • 区块内边距：
    4rem
  • 卡片圆角：
    1rem
    ，按钮圆角：
    2rem
  • 悬停提升效果：
    translateY(-6px)
  • 阴影：
    0 20px 60px rgba(0,0,0,0.15)

Common Gotchas

常见陷阱

  1. No HTML comments except block markers - Breaks WordPress block editor
  2. Always escape quotes in CSS strings - Use single quotes for content, attr values
  3. Duplicate properties - Put in both 
    styles
    and 
    css
    for consistency
  4. CSS alphabetically sorted - Properties in the 
    css
    string must be sorted alphabetically
  5. No hover/transitions in 
    css
     - The plugin generates hover states and transitions from the 
    styles
    object. Never put these in the 
    css
    attribute
  6. Cards with inner blocks = element block - Use 
    generateblocks/element
    (not 
    text
    ) for cards containing other blocks. Text blocks are leaf blocks (no inner blocks)
  7. Text 
    <a>
    = no htmlAttributes for href     - Link URL managed by editor UI. Element 
    <a>
    = use 
    htmlAttributes
    for href
  8. SVG icons = shape blocks - Use 
    generateblocks/shape
    for SVGs, not 
    generateblocks/element
    with raw SVG inside
  9. Pseudo-elements need content - 
    content:''
    for ::before/::after (these go in 
    css
    )
  10. Parent hover targeting children - Written in the child's 
    css
    : 
    .gb-element-card001:hover .gb-text-title001{color:#c0392b}
  11. Gradients only in CSS - Can't use in 
    styles
    attribute
  12. CSS variables work - Use 
    var(--custom-property)
    freely. Use 
    \u002d\u002d
    for 
    --
    in JSON
  13. Element blocks need className - Add 
    "className":"gb-element"
    to element block attributes
  14. Use !important sparingly - Only for overriding at breakpoints
  15. Lists use 
    core/list
    with 
    .list
    class     - Convert 
    <ul>
    /
    <ol>
    to native WordPress list block with 
    className: "list"
  16. Use 
    --gb-container-width
    for inner containers     - Set inner container width using the CSS variable; add 
    align: "full"
    to parent section
  17. Buttons with icons - Use 
    generateblocks/element
    (tagName 
    a
    ) wrapping 
    generateblocks/text
    + 
    generateblocks/shape
    blocks. Plain text buttons use 
    generateblocks/text
  1. 除区块标记外无其他HTML注释 - 会破坏WordPress区块编辑器
  2. 始终转义CSS字符串中的引号 - 内容和属性值使用单引号
  3. 重复属性 - 为保持一致性，同时放入
    styles
    和
    css
  4. CSS按字母顺序排序 - 
    css
    字符串中的属性必须按字母顺序排序
  5. css
    中无悬停/过渡效果     - 插件从
    styles
    对象生成悬停状态和过渡效果。绝不要将这些放入
    css
    属性
  6. 包含内部区块的卡片=元素区块 - 使用
    generateblocks/element
    （而非
    text
    ）包含其他区块的卡片。文本区块是叶子区块（无内部区块）
  7. 文本
    <a>
    =无需为href设置htmlAttributes     - 链接URL由编辑器界面管理。元素
    <a>
    =使用
    htmlAttributes
    设置href
  8. SVG图标=形状区块 - 使用
    generateblocks/shape
    处理SVG，而非在
    generateblocks/element
    中放入原始SVG
  9. 伪元素需要content - ::before/::after需设置
    content:''
    （放入
    css
    ）
  10. 父元素悬停触发子元素样式 - 写在子元素的
    css
    中：
    .gb-element-card001:hover .gb-text-title001{color:#c0392b}
  11. 渐变仅能放入CSS - 无法在
    styles
    属性中使用
  12. CSS变量可正常使用 - 自由使用
    var(--custom-property)
    。在JSON中用
    \u002d\u002d
    表示
    --
  13. 元素区块需要className - 为元素区块属性添加
    "className":"gb-element"
  14. 谨慎使用!important - 仅在断点处覆盖样式时使用
  15. 列表使用
    core/list
    并配合
    .list
    类     - 将
    <ul>
    /
    <ol>
    转换为原生WordPress列表区块并设置
    className: "list"
  16. 使用
    --gb-container-width
    设置内部容器     - 使用CSS变量设置内部容器宽度；为父区块添加
    align: "full"
  17. 带图标的按钮 - 使用
    generateblocks/element
    （tagName为
    a
    ）包裹
    generateblocks/text
    + 
    generateblocks/shape
    区块。纯文本按钮使用
    generateblocks/text

Performance Notes

性能说明

  • Inline styles are fast (no external CSS file)
  • Each block's CSS is scoped to its unique ID
  • GenerateBlocks automatically deduplicates common styles
  • Media queries only load when needed
  • Use 
    content-visibility: auto
    for off-screen sections
  • 内联样式加载速度快（无需外部CSS文件）
  • 每个区块的CSS都限定在其唯一ID范围内
  • GenerateBlocks自动去重通用样式
  • 媒体查询仅在需要时加载
  • 对屏幕外区块使用
    content-visibility: auto

Example: Complete Hero Section

示例：完整英雄区块

See 
to-convert/home-hero-v2.html
for a complete real-world example with:
  • Complex grid layout
  • Multiple nested components
  • Responsive breakpoints
  • Hover effects
  • Icon fonts
  • Images with overlays
请查看
to-convert/home-hero-v2.html
获取完整的真实示例，包含：
  • 复杂网格布局
  • 多个嵌套组件
  • 响应式断点
  • 悬停效果
  • 图标字体
  • 带遮罩的图片