WordPress Block Markup Converter

Convert between Markdown and WordPress block markup (the serialized HTML comment format used by Gutenberg).

When to use

• User asks to convert a .md file to WordPress block notation / Gutenberg markup
• User wants content they can paste into the WordPress Code Editor (Ctrl+Shift+Alt+M)
• User is building HTML templates for a block theme and needs properly delimited blocks
• User wants to convert block markup back to readable Markdown

How to use

Run the Python converter script bundled with this skill:

python3 /mnt/skills/user/wp-block-markup/scripts/md_to_blocks.py <input.md> <output.html>

The script handles: headings, paragraphs, fenced code blocks, ordered/unordered lists, blockquotes, tables, horizontal rules, and all inline formatting (bold, italic, code, links).

Quick integration pattern

import subprocess
result = subprocess.run(
    ["python3", "/mnt/skills/user/wp-block-markup/scripts/md_to_blocks.py", input_path, output_path],
    capture_output=True, text=True
)
print(result.stdout)  # Block count stats

Block grammar reference

WordPress block markup wraps HTML in comment delimiters. Every block has an opening comment and either a closing comment or is self-closing.

Core block patterns

Paragraph

<!-- wp:paragraph -->
<p>Text with <strong>bold</strong> and <a href="url">links</a>.</p>
<!-- /wp:paragraph -->

Heading (h2 is default, others need level attribute)

<!-- wp:heading -->
<h2 class="wp-block-heading">Section title</h2>
<!-- /wp:heading -->

<!-- wp:heading {"level":3} -->
<h3 class="wp-block-heading">Sub-section</h3>
<!-- /wp:heading -->

Code block

<!-- wp:code -->
<pre class="wp-block-code"><code lang="php" class="language-php">echo 'hello';</code></pre>
<!-- /wp:code -->

Unordered list (each item gets its own block comment)

<!-- wp:list -->
<ul class="wp-block-list">
<!-- wp:list-item -->
<li>First item</li>
<!-- /wp:list-item -->
<!-- wp:list-item -->
<li>Second item</li>
<!-- /wp:list-item -->
</ul>
<!-- /wp:list -->

Ordered list

<!-- wp:list {"ordered":true} -->
<ol class="wp-block-list">
<!-- wp:list-item -->
<li>Step one</li>
<!-- /wp:list-item -->
</ol>
<!-- /wp:list -->

Blockquote (inner content uses nested paragraph blocks)

<!-- wp:quote -->
<blockquote class="wp-block-quote">
<!-- wp:paragraph -->
<p>Quoted text here.</p>
<!-- /wp:paragraph -->
</blockquote>
<!-- /wp:quote -->

Table

<!-- wp:table -->
<figure class="wp-block-table"><table><thead><tr>
<th>Header 1</th>
<th>Header 2</th>
</tr></thead><tbody>
<tr>
<td>Cell 1</td>
<td>Cell 2</td>
</tr>
</tbody></table></figure>
<!-- /wp:table -->

Separator / horizontal rule

<!-- wp:separator -->
<hr class="wp-block-separator has-alpha-channel-opacity"/>
<!-- /wp:separator -->

Image

<!-- wp:image {"sizeSlug":"large"} -->
<figure class="wp-block-image size-large">
    <img src="source.jpg" alt="" />
</figure>
<!-- /wp:image -->

Self-closing / dynamic blocks (no inner HTML)

<!-- wp:search /-->
<!-- wp:latest-posts {"postsToShow":4,"displayPostDate":true} /-->

Key rules

1. Core blocks use wp:blockname (no core/ prefix). Custom blocks use wp:namespace/blockname.
2. Block attributes are a JSON object inside the opening comment: <!-- wp:heading {"level":3} -->.
3. The opening and closing comments wrap the HTML output of the block.
4. Content inside code blocks must be HTML-escaped (<, >, &, ").
5. Lists require <!-- wp:list-item --> wrappers around each <li>.
6. Blockquotes contain nested <!-- wp:paragraph --> blocks for their inner content.
7. Tables live inside a <figure class="wp-block-table"> wrapper.

Helpful references

• Markup representation of a block — official docs
• Block grammar basics — Full Site Editing course
• dmsnell/html-to-md — HTML→Markdown using the WordPress HTML API (reverse direction reference)
• wp-block-docs — searchable block HTML reference
• jeffreyducharme/wp-gutenberg-block-markup-cheat-sheet — cheat sheet with regex patterns

Output

The converter produces an .html file containing serialized block markup ready for:

• Pasting into the WordPress Code Editor
• Use in block theme HTML template files (templates/, parts/)
• Import via WP-CLI or the REST API