@wpgaurav/md-section

125+ reusable AI agent skills for Claude Code, ChatGPT, Cursor, and other AI tools — WordPress, design, SEO, marketing, frontend

View in AI SkillSafe app
Scanned · no findings
0 downloads
0 stars
0 demos
SKILL.md
namemd-section
descriptionUse when converting HTML layouts to MD Section block + core block combinations for the WordPress Block Editor. Triggers: HTML-to-blocks, section layout, convert HTML to Gutenberg, pasting HTML into block editor.

HTML to MD Section Block Conversion

Convert arbitrary HTML layouts into nested marketers-delight/section blocks combined with core WordPress blocks. Strip external CSS/JS. Preserve inline styles via block attributes.

When to Use

  • Converting an HTML template/component into block editor markup
  • Building complex layouts (heroes, card grids, tab panels) in the block editor
  • User pastes HTML and wants it as editable blocks
  • Recreating a design using Section blocks instead of Custom HTML

Section Block Reference

The MD Section block is a dynamic container. It renders server-side using attributes stored in the block comment delimiter. Inner blocks are stored as nested block markup.

Block Name

marketers-delight/section

Attributes

Attribute Type Default Purpose
htmlTag string div Tag name: div, section, article, aside, header, footer, main, nav, figure, details, or custom
customTag string "" Tag name when htmlTag is custom (e.g. dl, fieldset)
className string "" Space-separated CSS classes
anchor string "" HTML id attribute
align string "" wide or full
sectionCSS string "" Scoped CSS block (rendered in <style> tag before element)
htmlAttributes string "" Safe custom attributes as name="value" pairs (data-*, tabindex, style, title, etc.)
ariaHidden boolean false Sets aria-hidden="true"
ariaLabel string "" Sets aria-label
ariaLabelledBy string "" Sets aria-labelledby
role string "" ARIA role (banner, marquee, tabpanel, region, etc.) or custom
customRole string "" Role value when role is custom
hidden boolean false Sets hidden attribute

Serialization Format

<!-- wp:marketers-delight/section {"htmlTag":"section","className":"hero hero--dark","anchor":"top","ariaLabelledBy":"hero-title","sectionCSS":".hero--dark { background: #0a0a0a; color: #fff; }"} -->
<!-- inner blocks here -->
<!-- /wp:marketers-delight/section -->

Dynamic block: no HTML between delimiters except inner blocks. The PHP section() callback renders the wrapper element.

Safe htmlAttributes

The PHP renderer whitelists these attribute names/prefixes:

Prefixes: data-*, aria-* Names: tabindex, style, title, lang, dir, translate, loading, fetchpriority, rel, target, width, height, viewbox, preserveaspectratio, fill, stroke, opacity

Unsafe attributes (onclick, onerror, src, href) are silently dropped.

Conversion Rules

Step 1: Strip External Resources

Remove completely:

  • <link rel="stylesheet"> tags
  • <script src="..."> tags
  • <style> blocks that define external/global CSS

Step 2: Extract Scoped CSS

If the HTML has <style> blocks with classes used within the layout:

  • Move those rules into the outermost Section block's sectionCSS attribute
  • If CSS is section-specific, place it in that section's sectionCSS
  • Keep @keyframes and @media rules with the CSS they belong to

Step 3: Map Elements to Blocks

HTML Element                    Block
-----------------------------------------------------
<section>, <article>, <aside>,
<header>, <footer>, <nav>,
<main>, <figure>, <details>,
<div> (structural)             → marketers-delight/section

<h1>-<h6>                     → core/heading
<p>                            → core/paragraph
<ul>, <ol>                     → core/list + core/list-item
<img>                          → core/image
<video>                        → core/video
<audio>                        → core/audio
<blockquote>                   → core/quote
<pre>, <code>                  → core/code
<table>                        → core/table
<hr>                           → core/separator
<iframe> (embed)               → core/embed or core/html
<a> (wrapping block content)   → marketers-delight/section with htmlTag="a" is NOT supported; use core/group or nest a core/paragraph link
<svg> (inline, decorative)     → core/html
<dl>                           → marketers-delight/section with customTag="dl" + section children for dt/dd

Step 4: Transfer Attributes

For each HTML element mapped to a Section block:

HTML Attribute Section Block Property
class="..." className
id="..." anchor
role="..." role (or customRole if not in preset list)
aria-hidden="true" ariaHidden: true
aria-label="..." ariaLabel
aria-labelledby="..." ariaLabelledBy
hidden hidden: true
data-*="..." htmlAttributes string
tabindex="..." htmlAttributes string
style="..." htmlAttributes string (as style="...")

For core blocks, use their native attribute system (e.g., style object for headings/paragraphs).

Step 5: Handle Inline Styles

Inline style attributes on elements mapped to Section blocks go into htmlAttributes:

{"htmlAttributes":"style=\"--i:0\" data-panel=\"plugins\""}

For core blocks, convert inline styles to the block's style JSON object:

<!-- Input -->
<h1 style="font-size: 3rem; color: #fff; line-height: 1.1;">Title</h1>

<!-- Output -->
<!-- wp:heading {"level":1,"style":{"typography":{"fontSize":"3rem","lineHeight":"1.1"},"color":{"text":"#ffffff"}}} -->
<h1 class="wp-block-heading has-text-color" style="color:#ffffff;font-size:3rem;line-height:1.1">Title</h1>
<!-- /wp:heading -->

Output Format

Always output to a file, never inline in chat.

  • Filename: {descriptive-name}-blocks.html
  • Include only the block markup (no <!DOCTYPE>, no <html>/<body>)
  • No extra HTML comments. Only block editor comments (<!-- wp: and <!-- /wp:) are allowed. Never add descriptive comments like <!-- Hero section --> or <!-- Primary card -->
  • Brief summary in chat: what was converted, how many sections, any manual steps needed

Conversion Example

Input HTML

<section class="hero" id="top" aria-labelledby="hero-title">
  <style>.hero { background: #0a0a0a; } .hero__inner { max-width: 1200px; margin: 0 auto; }</style>
  <div class="hero__bg" aria-hidden="true"></div>
  <div class="hero__inner">
    <h1 id="hero-title" style="font-size: 3rem;">I build websites</h1>
    <p>Fast, accessible, and profitable.</p>
    <div class="hero__actions" data-section="cta">
      <a href="/contact/" class="button">Start a project</a>
    </div>
  </div>
</section>

Output Block Markup

<!-- wp:marketers-delight/section {"htmlTag":"section","className":"hero","anchor":"top","ariaLabelledBy":"hero-title","align":"full","sectionCSS":".hero { background: #0a0a0a; } .hero__inner { max-width: 1200px; margin: 0 auto; }"} -->

<!-- wp:marketers-delight/section {"htmlTag":"div","className":"hero__bg","ariaHidden":true} -->
<!-- /wp:marketers-delight/section -->

<!-- wp:marketers-delight/section {"htmlTag":"div","className":"hero__inner"} -->

<!-- wp:heading {"level":1,"anchor":"hero-title","style":{"typography":{"fontSize":"3rem"}}} -->
<h1 class="wp-block-heading" id="hero-title" style="font-size:3rem">I build websites</h1>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Fast, accessible, and profitable.</p>
<!-- /wp:paragraph -->

<!-- wp:marketers-delight/section {"htmlTag":"div","className":"hero__actions","htmlAttributes":"data-section=\"cta\""} -->

<!-- wp:paragraph -->
<p><a href="/contact/" class="button">Start a project</a></p>
<!-- /wp:paragraph -->

<!-- /wp:marketers-delight/section -->

<!-- /wp:marketers-delight/section -->

<!-- /wp:marketers-delight/section -->

Handling Complex Elements

SVG (Decorative)

Inline SVGs that are decorative (aria-hidden="true") convert to core/html:

<!-- wp:html -->
<svg class="bp__circuit" aria-hidden="true" viewBox="0 0 1600 900">
  <!-- SVG content preserved as-is -->
</svg>
<!-- /wp:html -->

Wrap in a Section block if the SVG needs positioning classes:

<!-- wp:marketers-delight/section {"htmlTag":"div","className":"bp__svg-wrap","ariaHidden":true} -->
<!-- wp:html -->
<svg>...</svg>
<!-- /wp:html -->
<!-- /wp:marketers-delight/section -->

Tab Panels

Use Section blocks with role, ariaLabelledBy, and hidden:

<!-- wp:marketers-delight/section {"htmlTag":"div","className":"panel active","anchor":"panel-plugins","role":"tabpanel","ariaLabelledBy":"tab-plugins"} -->
<!-- panel content blocks -->
<!-- /wp:marketers-delight/section -->

<!-- wp:marketers-delight/section {"htmlTag":"div","className":"panel","anchor":"panel-tools","role":"tabpanel","ariaLabelledBy":"tab-tools","hidden":true} -->
<!-- panel content blocks -->
<!-- /wp:marketers-delight/section -->

Definition Lists

Use Section with customTag:

<!-- wp:marketers-delight/section {"htmlTag":"custom","customTag":"dl","className":"stats-row"} -->
<!-- wp:marketers-delight/section {"htmlTag":"custom","customTag":"dt"} -->
<!-- wp:paragraph -->
<p>Label</p>
<!-- /wp:paragraph -->
<!-- /wp:marketers-delight/section -->
<!-- wp:marketers-delight/section {"htmlTag":"custom","customTag":"dd"} -->
<!-- wp:paragraph -->
<p>Value</p>
<!-- /wp:paragraph -->
<!-- /wp:marketers-delight/section -->
<!-- /wp:marketers-delight/section -->

Images

Always use core/image, not a Section block:

<!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="https://example.com/photo.jpg" alt="Description" /></figure>
<!-- /wp:image -->

Buttons / Links

Standalone text links inside a Section: use core/paragraph with an <a> tag inside.

Button groups: wrap in a Section block with the group class, use core/buttons + core/button inside:

<!-- wp:marketers-delight/section {"htmlTag":"div","className":"hero__actions"} -->
<!-- wp:buttons -->
<div class="wp-block-buttons">
<!-- wp:button {"className":"button"} -->
<div class="wp-block-button button"><a class="wp-block-button__link wp-element-button" href="/contact/">Start a project</a></div>
<!-- /wp:button -->
<!-- wp:button {"className":"button-outline"} -->
<div class="wp-block-button button-outline"><a class="wp-block-button__link wp-element-button" href="/work/">See my work</a></div>
<!-- /wp:button -->
</div>
<!-- /wp:buttons -->
<!-- /wp:marketers-delight/section -->

JavaScript Behavior

Strip <script> tags entirely. Note in the summary which interactive behaviors need reimplementation (tabs, accordions, marquees, etc.). Suggest:

  • Tabs: WordPress Interactivity API or custom dropin
  • Accordion: <details>/<summary> via Section blocks (native HTML)
  • Marquee/ticker: CSS animation in sectionCSS
  • Scroll effects: Intersection Observer via custom JS dropin

Common Mistakes

Mistake Fix
Putting HTML between Section block delimiters Section is dynamic. Only inner blocks go between delimiters
Using Section for <img> Use core/image
Using Section for <h1>-<h6> Use core/heading
Using Section for <p> Use core/paragraph
Keeping <script> tags Strip completely, note in summary
Putting global CSS in every section's sectionCSS Put shared CSS in the outermost section only
Using onclick or event handlers in htmlAttributes These are blocked by the sanitizer
Forgetting to escape quotes in htmlAttributes Use \" inside the JSON string: "htmlAttributes":"data-x=\"val\""
Omitting default attribute values Only include non-default values in the JSON (no "htmlTag":"div" since div is default)
Adding descriptive HTML comments Only <!-- wp: block comments allowed. No <!-- Section name --> or <!-- Card -->

Embed badges

Add these to your README to show the skill's verification status.

SkillSafe verified badge
Verified badge
[![SkillSafe verified badge](https://api.skillsafe.ai/v1/badge/@wpgaurav/md-section/verified)](https://skillsafe.ai/skill/@wpgaurav/md-section/)
Installs badge
Installs badge
[![Installs badge](https://api.skillsafe.ai/v1/badge/@wpgaurav/md-section/installs)](https://skillsafe.ai/skill/@wpgaurav/md-section/)
Scan badge
Scan badge
[![Scan badge](https://api.skillsafe.ai/v1/badge/@wpgaurav/md-section/scan)](https://skillsafe.ai/skill/@wpgaurav/md-section/)
Eval pass rate badge
Eval pass rate
[![Eval pass rate badge](https://api.skillsafe.ai/v1/badge/@wpgaurav/md-section/eval)](https://skillsafe.ai/skill/@wpgaurav/md-section/)