### Start Development Server

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/README.md

Run this command in your block plugin directory to start the development server and watch for changes.

```bash
cd html-to-gutenberg-blocks # Your block plugin directory
npm run start
```

--------------------------------

### Install Dependencies

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/README.md

Installs project dependencies using Yarn. This is the first step before running any other commands.

```bash
yarn
```

--------------------------------

### Start Development Server

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/common/_quick-start.md

Navigate to your new block plugin directory and start the development server. This command enables live reloading for your block development.

```bash
cd html-to-gutenberg-blocks
npm run start
```

--------------------------------

### Start Local Development Server

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/README.md

Starts a local development server that automatically refreshes the browser on code changes. Useful for active development.

```bash
yarn start
```

--------------------------------

### Install HTML To Gutenberg via npm

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/getting-started/installation.mdx

Use this command to add HTML To Gutenberg as a development dependency to your project.

```bash
npm install @jverneaut/html-to-gutenberg --save-dev
```

--------------------------------

### Live Editor Example with InnerBlocks Template

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/inner-blocks.mdx

Demonstrates a complex InnerBlocks template with nested blocks and attributes using the LiveEditor.

```html
<section>
  <inner-blocks templateLock>
    <inner-block name="core/group">
      <inner-block name="core/heading" level="3"></inner-block>
      <inner-block name="core/paragraph">
        <block-attribute name="content">
          Lorem <strong>ipsum</strong>
        </block-attribute>
      </inner-block>
    </inner-block>
  </inner-blocks>
</section>
```

--------------------------------

### Scaffold with @wordpress/create-block

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Use this command to scaffold a new block project using the html-to-gutenberg template. After scaffolding, run `npm run start` for development or `npm run build` for production.

```bash
cd wp-content/plugins
npx @wordpress/create-block --template html-to-gutenberg-template

cd html-to-gutenberg-blocks
npm run start   # development — watches src/ and rebuilds automatically
npm run build   # production bundle
```

--------------------------------

### Live HTML to Gutenberg Block Editor Example

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/introduction.mdx

Use this live editor to experiment with HTML structure, attributes, and InnerBlocks to see how they translate into Gutenberg blocks. It supports features like data binding and inspector controls.

```html
<section
  class="py-20 bg-blue-200"
  data-parent="custom/parent-block"
  data-editing-mode="contentOnly"
>
  <inspector-controls>
    <panel-body title="Settings">
      <select-control data-bind="postType" label="Post Type">
        <select-control-option value="posts">Posts</select-control-option>
        <select-control-option value="pages">Pages</select-control-option>
      </select-control>
    </panel-body>
  </inspector-controls>

  <div class="container">
    <div class="grid grid-cols-12 gap-4">
      <div class="col-span-12 md:col-span-6">
        <h2 class="text-2xl" data-bind="sectionTitle">
          Edit me inside the editor
        </h2>
        <img class="aspect-square object-cover" data-bind="sectionImage" />
      </div>

      <div class="col-span-12 md:col-span-6">
        <inner-blocks allowedBlocks="all" templateLock="all">
          <inner-block name="core/group">
            <inner-block name="core/heading" level="3"></inner-block>
            <inner-block name="core/paragraph">
              <block-attribute name="content">
                Lorem ipsum dolor sit amet consectetur.
              </block-attribute>
            </inner-block>
          </inner-block>
        </inner-blocks>
      </div>
    </div>

  </div>
</section>
```

--------------------------------

### Registering Post Meta for REST API Exposure

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/data-binding.mdx

Example of registering post meta using `register_post_meta` in PHP, ensuring it's exposed to the REST API for editing via `data-bind`.

```php
register_post_meta('recipe', 'cooking_time', [
  'show_in_rest' => true, // Expose in REST API
  'single' => true,       // Only store a single value (not an array)
  'type' => 'string',     // Data type (adjust as needed: string, boolean, integer, etc.)
]);
```

--------------------------------

### Manual Webpack Integration

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Install the package and add the HTMLToGutenbergPlugin to your webpack configuration. This plugin automatically hooks into Webpack's build process to handle HTML to Gutenberg block compilation.

```bash
npm install @jverneaut/html-to-gutenberg --save-dev
```

```javascript
// webpack.config.js
import HTMLToGutenbergPlugin from "@jverneaut/html-to-gutenberg";

export default {
  plugins: [
    new HTMLToGutenbergPlugin({
      inputDirectory: "./blocks",           // source .html files
      outputDirectory: "./generated-blocks", // generated edit.js / render.php / …
      defaultNamespace: "custom",           // block name prefix  (default: "custom")
      defaultCategory: "theme",             // block category     (default: "theme")
      defaultVersion: "0.1.0",             // block version      (default: "0.1.0")
    }),
  ],
};
```

--------------------------------

### Styling Block Styles with CSS

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/block-attributes/block-styles.mdx

Apply custom styles to your block by targeting the generated `.is-style-{style-slug}` CSS classes. This example shows how to style a block with the 'dark' style.

```css
.wp-block-custom-block-with-styles.is-style-dark {
  background: black;
  color: white;
}
```

--------------------------------

### Server-Side Block with Inspector Controls

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/server-side-blocks.mdx

This example demonstrates how to pass attributes from inspector controls to a server-side rendered block. The `postType` attribute is selected in the editor and used in the PHP render file.

```html
<section>
    <inspector-controls>
      <panel-body title="Query Settings">
        <select-control label="Post Type" data-bind="postType">
          <select-control-option value="post">Post</select-control-option>
          <select-control-option value="page">Page</select-control-option>
          <select-control-option value="product">Product</select-control-option>
        </select-control>
      </panel-body>
    </inspector-controls>

    <!-- The block calls itself to display posts using the latest-posts.render.php override -->
    <server-block name="custom/latest-posts"></server-block>

  </section>
```

```php
<?php

$post_type = $attributes['postType'] ?? 'post';

$latest_posts = get_posts([
  'post_type' => $post_type,
  'posts_per_page' => 5,
]);

?>

<section <?= get_block_wrapper_attributes(); ?>
  <?php foreach ($latest_posts as $post) : ?>
    <article>
      <h3><?= esc_html($post->post_title); ?></h3>
      <a href="<?= esc_url(get_permalink($post)); ">Read more</a>
    </article>
  <?php endforeach; ?>
</section>
```

--------------------------------

### Integrate HTML To Gutenberg with GutenbergWebpackPlugin

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/getting-started/installation.mdx

Combine HTMLToGutenbergPlugin with GutenbergWebpackPlugin in your webpack.config.js for a streamlined block development workflow. This setup generates block files and registers them.

```javascript
import HTMLToGutenbergPlugin from "@jverneaut/html-to-gutenberg";
import GutenbergWebpackPlugin from "@jverneaut/gutenberg-webpack-plugin";

export default {
  mode: "development",
  entry: "./index.js", // Your main entry point for non-Gutenberg scripts

  plugins: [
    new HTMLToGutenbergPlugin({
      inputDirectory: "./blocks", // Source folder for your custom blocks HTML
      outputDirectory: "./generated-blocks", // Where transformed blocks will be output
    }),

    new GutenbergWebpackPlugin("./generated-blocks"), // Registers the generated blocks
  ],
};
```

--------------------------------

### HTML Element Visibility with data-display

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/elements-visibility.mdx

Use the `data-display` attribute to control element visibility. Supported values include `frontend`, `editor`, `selected`, and `not-selected`. This example demonstrates all options.

```html
<section>
    <div>Visible everywhere</div>
    <div data-display="frontend">Visible on the frontend only</div>
    <div data-display="editor">Visible in the editor only</div>
    <div data-display="selected">
      Visible in the editor when the block is selected only
    </div>
    <div data-display="not-selected">
      Visible in the editor when the block is not selected only
    </div>
  </section>
```

--------------------------------

### Combine Custom Variants with Tailwind Modifiers

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/extra/tailwindcss.mdx

Apply styles to specific child blocks within a container by combining custom Tailwind variants with other modifiers. This example styles the first 'core/heading' block inside a group.

```html
<section class="py-20">
    <div class="wp-block-heading:first-of-type:text-red-600 wp-block-group:p-10">
      <inner-blocks templateLock="all">
        <inner-block name="core/group">
          <inner-block name="core/heading" content="I am red"></inner-block>
          <inner-block name="core/heading" content="I am not red"></inner-block>
        </inner-block>
      </inner-blocks>
    </div>
  </section>
```

--------------------------------

### Hero Block with Two Editable Zones

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/inner-blocks.mdx

Example of a Hero block with two distinct editable regions using nested InnerBlocks. The main block defines the layout, and child blocks define the content areas.

```html
<section class="hero">
  <div class="hero__container">
    <inner-blocks>
      <inner-block name="custom/hero-top"></inner-block>
      <inner-block name="custom/hero-bottom"></inner-block>
    </inner-blocks>
  </div>
</section>
```

```html
<div class="hero__top">
  <inner-blocks>
    <inner-block name="core/heading" level="1"></inner-block>
    <inner-block name="core/paragraph"></inner-block>
    <inner-block name="core/buttons"></inner-block>
  </inner-blocks>
</div>
```

```html
<div class="hero__bottom">
  <inner-blocks>
    <inner-block name="core/paragraph"></inner-block>
  </inner-blocks>
</div>
```

--------------------------------

### Build for Production

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/common/_quick-start.md

Run this command to bundle and minify your blocks for production deployment. This optimizes your plugin for performance.

```bash
npm run build
```

--------------------------------

### Build Static Website

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/README.md

Generates the static website files into the 'build' directory. These files can then be hosted on any static hosting service.

```bash
yarn build
```

--------------------------------

### CLI Usage for HTML to Gutenberg

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Use the CLI tool for one-shot generation or to enable watch mode for automatic regeneration on file changes. Flags include input/output directories and a namespace prefix.

```bash
# One-shot generation
npx @jverneaut/html-to-gutenberg -i ./src -o ./generated-blocks -p custom

# Watch mode — regenerates on every .html change
npx @jverneaut/html-to-gutenberg -i ./src -o ./generated-blocks --watch
```

--------------------------------

### Project Structure for HTML Blocks

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/creating-a-block.mdx

This tree structure illustrates where to place your HTML files and where the generated block files will reside. Adding `.html` files to the `src/` directory automatically generates corresponding block files.

```txt
.\nT├── src/\n│   ├── first-block.html\n│   ├── second-block.html\n│   └── ... # Add more blocks by adding files here\n├── generated-blocks/\n│   ├── first-block/\n│   │   ├── block.json\n│   │   ├── edit.js\n│   │   ├── index.js\n│   │   └── render.php\n│   └── second-block/\n│       ├── block.json\n│       ├── edit.js\n│       ├── index.js\n│       └── render.php\n└── build/\n    ├── first-block/\n    │   └── ...\n    └── second-block/\n        └── ...\n
```

--------------------------------

### Deploy Website (SSH)

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/README.md

Deploys the website using SSH. This command builds the static content and pushes it to the 'gh-pages' branch, suitable for GitHub Pages.

```bash
USE_SSH=true yarn deploy
```

--------------------------------

### Scaffold HTML To Gutenberg Plugin

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/common/_quick-start.md

Use this command to create a new WordPress plugin pre-configured with the HTML To Gutenberg template. Ensure you are in the correct directory before running.

```bash
cd wp-content/plugins
npx @wordpress/create-block --template html-to-gutenberg-template
```

--------------------------------

### Deploy Website (No SSH)

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/README.md

Deploys the website without using SSH. Requires specifying your GitHub username. This command builds and pushes to the 'gh-pages' branch.

```bash
GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Target Specific Blocks with Custom Tailwind Variants

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/extra/tailwindcss.mdx

Define custom CSS variants for specific Gutenberg blocks to apply styles to child blocks from their container. This example shows variants for heading and group blocks.

```css
/* Do this for each block you want to target */
@custom-variant wp-block-heading {
  .wp-block-heading {
    @slot;
  }
}

@custom-variant wp-block-group {
  .wp-block-group {
    @slot;
  }
}
```

--------------------------------

### Add Inspector Controls Panels

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/inspector-controls.mdx

Use `<inspector-controls>` and `<panel-body>` to create collapsible panels in the block sidebar for organizing settings.

```html
<section>
    <inspector-controls>
      <panel-body title="Query settings">
        <!-- ... -->
      </panel-body>
      <panel-body title="Display settings">
        <!-- ... -->
      </panel-body>
    </inspector-controls>
  </section>
```

--------------------------------

### Add Toolbar Controls with `<block-controls>`

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Use `<block-controls>` to add custom toolbar controls to your Gutenberg block. Bind attributes using `data-bind` for dynamic updates.

```html
<section>
  <block-controls>
    <toolbar-group>
      <!-- Toggles the "darkMode" boolean attribute -->
      <toolbar-button data-bind="darkMode" icon="styles"></toolbar-button>

      <!-- Dropdown acting like a <select> for the "direction" attribute -->
      <toolbar-dropdown-menu
        icon="more"
        label="Select direction"
        data-bind="direction"
      >
        <toolbar-dropdown-menu-option icon="arrowUp"    value="up">Up</toolbar-dropdown-menu-option>
        <toolbar-dropdown-menu-option icon="arrowRight" value="right">Right</toolbar-dropdown-menu-option>
        <toolbar-dropdown-menu-option icon="arrowDown"  value="down">Down</toolbar-dropdown-menu-option>
        <toolbar-dropdown-menu-option icon="arrowLeft"  value="left">Left</toolbar-dropdown-menu-option>
      </toolbar-dropdown-menu>
    </toolbar-group>
  </block-controls>

  <div class="{attributes.darkMode ? 'bg-black text-white' : 'bg-white text-black'}">
    Content here
  </div>
</section>
```

--------------------------------

### Git Ignore Recommendation

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/creating-a-block.mdx

To prevent committing generated block files and build artifacts to your repository, add these entries to your `.gitignore` file. This is particularly useful in CI/CD workflows.

```txt
generated-blocks # The folder where your blocks are generated\ndist\n
```

--------------------------------

### Add Interactive Toolbar Controls with BlockControls

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/block-controls.mdx

Implement interactive toolbar controls like toggles and dropdowns using `<toolbar-button>` and `<toolbar-dropdown-menu>`. These can be data-bound to block attributes for dynamic behavior.

```html
<section>
    <block-controls>
      <toolbar-group>
        <toolbar-button data-bind="darkMode" icon="styles"></toolbar-button>
        <toolbar-dropdown-menu
          icon="more"
          label="Select a direction"
          data-bind="direction"
        >
          <toolbar-dropdown-menu-option icon="arrowUp" value="up">Up</toolbar-dropdown-menu-option>
          <toolbar-dropdown-menu-option icon="arrowRight" value="right">Right</toolbar-dropdown-menu-option>
          <toolbar-dropdown-menu-option icon="arrowDown" value="down">Down</toolbar-dropdown-menu-option>
          <toolbar-dropdown-menu-option icon="arrowLeft" value="left">Left</toolbar-dropdown-menu-option>
        </toolbar-dropdown-menu>
      </toolbar-group>
    </block-controls>

  </section>
```

--------------------------------

### Add Custom Blocks

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/common/_quick-start.md

Create new Gutenberg blocks by adding HTML files to the 'src' directory. Each HTML file will be automatically converted into a functional Gutenberg block.

```text
src/
├── block.html         # Default block (can be safely deleted)
├── hero.html          # Another custom block
├── testimonial.html   # Yet another one
```

--------------------------------

### Server-Side Rendering with `<server-block>`

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Implement server-side rendering for your Gutenberg block using the `<server-block>` element. Pass block attributes directly to your PHP render file.

```html
<section>
  <inspector-controls>
    <panel-body title="Query Settings">
      <select-control label="Post Type" data-bind="postType">
        <select-control-option value="post">Post</select-control-option>
        <select-control-option value="page">Page</select-control-option>
        <select-control-option value="product">Product</select-control-option>
      </select-control>
    </panel-body>
  </inspector-controls>

  <!-- Renders the block server-side in the editor; $attributes available in render.php -->
  <server-block name="custom/latest-posts"></server-block>
</section>
```

```php
<?php
$post_type   = $attributes['postType'] ?? 'post';
$latest_posts = get_posts(['post_type' => $post_type, 'posts_per_page' => 5]);
?>
<section <?= get_block_wrapper_attributes(); ?>
  <?php foreach ($latest_posts as $post) : ?>
    <article>
      <h3><?= esc_html($post->post_title); ?></h3>
      <a href="<?= esc_url(get_permalink($post)); ">Read more</a>
    </article>
  <?php endforeach; ?>
</section>
```

--------------------------------

### Provide Block Description with data-description

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/block-attributes/block-information.mdx

Add the `data-description` attribute to the root element to provide a description for your block. This can help users understand the block's purpose.

```html
<section data-description="Custom description"></section>
```

--------------------------------

### Gutenberg Block Configuration (block.json)

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/common/_example.md

This JSON file defines the metadata and configuration for a Gutenberg block. It specifies the block's name, title, category, attributes, editor script, and render callback. Essential for registering and managing block properties.

```json
{
  "name": "custom/block",
  "title": "Block",
  "textdomain": "block",
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "version": "0.1.0",
  "category": "theme",
  "example": {},
  "parent": ["custom/parent-block"],
  "attributes": {
    "align": { "type": "string", "default": "full" },
    "sectionImage": { "type": "integer" },
    "postType": { "type": "string", "default": "posts" },
    "sectionTitle": { "type": "string", "default": "Edit me inside the editor" }
  },
  "supports": { "html": false, "align": ["full"] },
  "editorScript": "file:./index.js",
  "render": "file:./render.php"
}
```

--------------------------------

### Binding Post Meta with data-bind

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/data-binding.mdx

Use `data-bind="postMeta.your_meta_key"` to bind to and edit post meta. The meta key must be registered, exposed via the REST API, and stored as a single value.

```html
<section class="recipe">
    <!-- This will allow you to edit post meta in the editor -->
    <p>Cooking time: <span data-bind="postMeta.cooking_time">60min</span></p>
    <p>Number of persons: <span data-bind="postMeta.number_of_persons">1-2</span></p>

    <select data-bind="postMeta.recipe_type">
      <option value="healthy">Healthy</option>
      <option value="super_fat">Super fat</option>
      <option value="smelly">Smelly</option>
    </select>

  </section>
```

--------------------------------

### Replace data-attributes with data-bind

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/migration-guide.mdx

Use `data-bind` to bind post title, custom post meta, and block attributes. It defaults to `attributes.[key]`.

```html
<section class="hero">
    <!-- Binding to the post title and custom post meta -->
    <h1 data-bind="post.title">Post title</h1>
    <p data-bind="postMeta.description">Custom post description meta</p>

    <!-- Equivalent, data-bind defaults to attributes.[key] -->
    <input type="text" data-bind="customAttributes">
    <input type="text" data-bind="attributes.customAttribute">

  </section>
```

--------------------------------

### File Overrides

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Override any generated file by placing a companion file alongside the `.html` source. Extra files like images and fonts are copied as-is into the output block folder.

```APIDOC
## File overrides

Override any generated file by placing a companion file alongside the `.html` source. Extra files (images, fonts, etc.) are copied as-is into the output block folder.

```
src/
├── hero.html               # block definition
├── hero.edit.js            # overrides generated edit.js
├── hero.render.php         # overrides generated render.php
├── hero.block.json         # overrides generated block.json
├── hero.index.js           # overrides generated index.js
└── hero.style.css          # copied to generated-blocks/hero/style.css
```

For folder-based blocks (`hero/index.html`):

```
src/hero/
├── index.html
├── edit.js                 # overrides generated edit.js
├── render.php              # overrides generated render.php
└── custom-image.jpg        # copied as-is
```
```

--------------------------------

### Integrate Content Picker with <content-picker>

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Use the `<content-picker>` component to allow editors to select posts directly in the sidebar. Binds selected post IDs to a block attribute.

```html
<!-- src/posts-slider.html -->
<section>
  <inspector-controls>
    <panel-body title="Settings">
      <!-- Binds selected post IDs to the "posts" block attribute -->
      <content-picker
        data-bind="posts"
        max-content-items="5"
      ></content-picker>
    </panel-body>
  </inspector-controls>

  <!-- Renders the list server-side using the selected post IDs -->
  <server-block name="custom/posts-slider"></server-block>
</section>
```

--------------------------------

### Register Custom Blocks Manually

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/getting-started/registering-blocks.md

Add this PHP snippet to your theme's `functions.php` file or a custom plugin to register blocks. Ensure the `$blocks_path` variable correctly points to your build output directory.

```php
add_action('init', function () {
    // Update this path to match your build output directory
    $blocks_path = get_stylesheet_directory() . '/dist/blocks';
    $blocks = array_filter(glob($blocks_path . '/**/*'), 'is_dir');

    foreach ($blocks as $block) {
        register_block_type($block);
    }
});
```

--------------------------------

### Render Block Content in PHP

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/README.md

Defines the server-side rendering logic for the Gutenberg block. It retrieves attributes like section image, title, and content to dynamically generate HTML output. Ensure all necessary WordPress functions are available.

```php
<?php

$sectionImage_id = $attributes['sectionImage'] ?? '';
$sectionImage = $sectionImage_id ? wp_get_attachment_image_src($sectionImage_id, 'full') : [''];
$sectionImage_src = $sectionImage[0] ?? '';
$sectionImage_srcset = $sectionImage_id ? wp_get_attachment_image_srcset($sectionImage_id, 'full') : '';
$sectionImage_sizes = $sectionImage_id ? wp_get_attachment_image_sizes($sectionImage_id, 'full') : '';
$sectionImage_alt = $sectionImage_id ? get_post_meta($sectionImage_id, '_wp_attachment_image_alt', true) : '';

?>

<section <?php echo get_block_wrapper_attributes(['class' => 'py-20 bg-blue-200']); ?>>
  <div class="container">
    <div class="grid grid-cols-12 gap-4">
      <div class="col-span-12 md:col-span-6">
        <h2 class="text-2xl"><?php echo wp_kses_post($attributes['sectionTitle'] ?? ''); ?></h2>
        <img class="aspect-square object-cover" src="<?php echo esc_url($sectionImage_src); ?>" srcset="<?php echo esc_attr($sectionImage_srcset); ?>" sizes="<?php echo esc_attr($sectionImage_sizes); ?>" alt="<?php echo esc_attr($sectionImage_alt); ?>" />
      </div>
      <div class="col-span-12 md:col-span-6">
        <?php echo $content; ?>
      </div>
    </div>
  </div>
</section>
```

--------------------------------

### File Overrides for Block Definitions

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Override generated block files by placing companion files alongside the `.html` source. Extra assets are copied as-is.

```text
src/
├── hero.html               # block definition
├── hero.edit.js            # overrides generated edit.js
├── hero.render.php         # overrides generated render.php
├── hero.block.json         # overrides generated block.json
├── hero.index.js           # overrides generated index.js
└── hero.style.css          # copied to generated-blocks/hero/style.css
```

```text
src/hero/
├── index.html
├── edit.js                 # overrides generated edit.js
├── render.php              # overrides generated render.php
└── custom-image.jpg        # copied as-is
```

--------------------------------

### Organize Toolbar Controls with ToolbarGroup

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/block-controls.mdx

Use `<toolbar-group>` to group related toolbar controls within the `<block-controls>` element. This helps in organizing the UI of your block's toolbar.

```html
<section>
    <block-controls>
      <toolbar-group>
        <!-- Your grouped controls here -->
      </toolbar-group>
    </block-controls>
  </section>
```

--------------------------------

### HTMLToGutenberg Programmatic API

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Utilize the `HTMLToGutenberg` class for a lower-level API to integrate the compiler into non-Webpack toolchains, programmatically generating Gutenberg blocks from HTML content.

```APIDOC
## HTMLToGutenberg programmatic API

The `HTMLToGutenberg` class provides a lower-level API for integrating the compiler into non-Webpack toolchains.

```js
import HTMLToGutenberg from "@jverneaut/html-to-gutenberg/src/HTMLToGutenberg.js";
import processors from "@jverneaut/html-to-gutenberg/src/processors/index.js";
import printers   from "@jverneaut/html-to-gutenberg/src/printers/index.js";
import fs from "fs/promises";

const compiler = new HTMLToGutenberg({
  printers,
  processors,
  defaultNamespace: "custom",
  defaultCategory:  "theme",
  defaultVersion:   "0.1.0",
  defaultIcon:      null,
});

const htmlContent = await fs.readFile("./src/hero.html", "utf-8");

const result = await compiler.printBlockFromHTMLFileContent(htmlContent, {
  name:       "custom/hero",
  textdomain: "hero",
  title:      "Hero",
});

// result.files = { "edit.js": "…", "render.php": "…", "block.json": "…", "index.js": "…" }
// result.dependencies = […]  (npm packages needed by the block)

for (const [filename, content] of Object.entries(result.files)) {
  await fs.writeFile(`./generated-blocks/hero/${filename}`, content);
}
```
```

--------------------------------

### Basic InnerBlocks with Locked Template

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Define a locked template for nested blocks using `<inner-blocks templateLock="all">`. Specify allowed blocks and default inner blocks.

```html
<!-- src/hero.html -->
<section class="hero">
  <inner-blocks templateLock="all" allowedBlocks="core/heading core/paragraph core/buttons">
    <inner-block name="core/heading" level="1" content="Hero Title"></inner-block>
    <inner-block name="core/paragraph">
      <block-attribute name="content">
        Subtitle text with <strong>rich</strong> content.
      </block-attribute>
    </inner-block>
    <inner-block name="core/buttons"></inner-block>
  </inner-blocks>
</section>
```

--------------------------------

### Add Plugin Name to PHP File

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/common/_quick-start.md

If your plugin does not appear in the WordPress admin, ensure a 'Plugin Name' is set in the root PHP file. This is crucial for WordPress to recognize the plugin.

```php
<?php

/**
 * Plugin Name:       HTML To Gutenberg Blocks <------ Add a name here
 * Version:           0.1.0
 * Requires at least: 6.7
 * Requires PHP:      7.4
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       textdomain
 *
 * @package CreateBlock
 */

```

--------------------------------

### Bind HTML to Post Meta

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Bind elements to post meta fields using `data-bind="postMeta.<meta_key>"`. Ensure post meta is registered with `show_in_rest: true`.

```html
<!-- src/recipe.html -->
<section class="recipe">
  <p>Cooking time: <span data-bind="postMeta.cooking_time">60min</span></p>
  <p>Persons: <span data-bind="postMeta.number_of_persons">1-2</span></p>

  <select data-bind="postMeta.recipe_type">
    <option value="healthy">Healthy</option>
    <option value="super_fat">Super fat</option>
  </select>
</section>
```

--------------------------------

### Block Metadata with Global Stylesheet

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/styles-and-scripts.mdx

This JSON represents the `block.json` file, demonstrating how the `style` property is automatically populated when using the `data-style` attribute. This ensures the stylesheet is loaded by WordPress.

```json
{
  "name": "custom/block",
  "title": "Block",
  "textdomain": "block",
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "example": {},
  "attributes": { "align": { "type": "string", "default": "full" } },
  "supports": { "html": false, "align": ["full"] },
  "editorScript": "file:./index.js",
  "render": "file:./render.php",
  // highlight-next-line
  "style": "file:./style-index.css"
}
```

--------------------------------

### Block Metadata with View Script

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/styles-and-scripts.mdx

This JSON represents the `block.json` file, demonstrating how the `viewScript` property is automatically populated when using the `data-view-script` attribute. This ensures the script is loaded on the frontend.

```json
{
  "name": "custom/block",
  "title": "Block",
  "textdomain": "block",
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "example": {},
  "attributes": { "align": { "type": "string", "default": "full" } },
  "supports": { "html": false, "align": ["full"] },
  "editorScript": "file:./index.js",
  "render": "file:./render.php",
  // highlight-next-line
  "viewScript": "file:./viewScript.js" # Can be any other file name, no transform happens here
}
```

--------------------------------

### Render a Server-Side Block

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/server-side-blocks.mdx

Use the `name` attribute to specify which block to render server-side. This is useful for blocks that require dynamic data or server-side logic.

```html
<section>
    <server-block name="custom/latest-posts-slider"></server-block>
  </section>
```

--------------------------------

### Configure Block Metadata with Root `data-*` Attributes

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Define block metadata such as name, title, icon, and category by adding `data-*` attributes to the root HTML element of your block.

```html
<section
  data-name="custom-ns/my-hero"
  data-title="My Hero Block"
  data-description="A full-width hero section"
  data-icon="star"
  data-category="theme"
  data-align="full wide"
  data-styles="default dark"
  data-editing-mode="contentOnly"
  data-parent="custom/page-layout"
  data-style="style.css"
  data-editor-style="edit.css"
  data-view-script="viewScript.js"
  data-version="1.2.0"
>
  <h2 data-bind="title">Hero Title</h2>
</section>
```

--------------------------------

### Configure HTML To Gutenberg Plugin in Webpack

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/getting-started/installation.mdx

Add the HTMLToGutenbergPlugin to your webpack.config.js to automatically generate block files from HTML. Specify input and output directories.

```javascript
import HTMLToGutenbergPlugin from "@jverneaut/html-to-gutenberg";

export default {
  plugins: [
    new HTMLToGutenbergPlugin({
      inputDirectory: "./blocks",
      outputDirectory: "./generated-blocks",
    }),
  ],
};
```

--------------------------------

### Setting Default Block Attributes with <block-attribute>

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/inner-blocks.mdx

Use the <block-attribute> element with 'name' and 'value' attributes to explicitly set block attributes.

```html
<section>
  <inner-blocks>
    <inner-block name="core/heading" level="2">
      <block-attribute name="content" value="Section title"></block-attribute>
    </inner-block>
  </inner-blocks>
</section>
```

--------------------------------

### Block Metadata with Editor Stylesheet

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/styles-and-scripts.mdx

This JSON represents the `block.json` file, demonstrating how the `editorStyle` property is automatically populated when using the `data-editor-style` attribute. This ensures the stylesheet is loaded only in the editor.

```json
{
  "name": "custom/block",
  "title": "Block",
  "textdomain": "block",
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "example": {},
  "attributes": { "align": { "type": "string", "default": "full" } },
  "supports": { "html": false, "align": ["full"] },
  "editorScript": "file:./index.js",
  "render": "file:./render.php",
  // highlight-next-line
  "editorStyle": "file:./index.css"
}
```

--------------------------------

### Referencing Data in HTML Attributes

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/expressions.mdx

Access data from 'attributes', 'postMeta', or 'post' objects directly within attribute expressions using dot notation. Ensure the referenced keys exist to avoid errors.

```html
<div
  id="{attributes.id}"
  class="{postMeta.theme === 'dark' ? 'theme-dark' : 'theme-light'}"
></div>
```

--------------------------------

### Add Various Form Controls to Inspector Panels

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/inspector-controls.mdx

Integrate standard Gutenberg form controls like text, checkbox, toggle, radio, and select inputs. Bind these controls to block attributes or post meta using the `data-bind` attribute.

```html
<section>
    <inspector-controls>
      <panel-body title="Settings">
        <text-control label="Checkbox" data-bind="isChecked"></text-control>
        <toggle-control label="Toggle" data-bind="isToggled"></toggle-control>

        <radio-control label="Radio" data-bind="choice">
          <radio-control-option value="a">Option A</radio-control-option>
          <radio-control-option value="b">Option B</radio-control-option>
          <radio-control-option value="c">Option C</radio-control-option>
        </radio-control>

        <select-control label="Select" data-bind="selectChoice">
          <select-control-option value="a">Option A</select-control-option>
          <select-control-option value="b">Option B</select-control-option>
          <select-control-option value="c">Option C</select-control-option>
        </select-control>
      </panel-body>
    </inspector-controls>

  </section>
```

--------------------------------

### Inspector Controls for Block Sidebar

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Use `<inspector-controls>` and `<panel-body>` to create sidebar controls for a block. Supported controls include text, checkbox, toggle, radio, and select.

```html
<!-- src/query-block.html -->
<section>
  <inspector-controls>
    <panel-body title="Query Settings">

      <text-control
        label="Custom label"
        data-bind="customLabel"
      ></text-control>

      <toggle-control
        label="Show excerpt"
        data-bind="showExcerpt"
      ></toggle-control>

      <radio-control label="Layout" data-bind="layout">
        <radio-control-option value="grid">Grid</radio-control-option>
        <radio-control-option value="list">List</radio-control-option>
      </radio-control>

      <select-control label="Post type" data-bind="postType">
        <select-control-option value="post">Post</select-control-option>
        <select-control-option value="page">Page</select-control-option>
        <select-control-option value="product">Product</select-control-option>
      </select-control>

    </panel-body>
  </inspector-controls>

  <div class="posts-grid" data-bind="layout">Grid layout</div>
</section>
```

--------------------------------

### Add Global Stylesheet to Block

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/styles-and-scripts.mdx

Use the `data-style` attribute in your HTML to specify a stylesheet that will be loaded globally for the block. This automatically adds an import to the block's main JavaScript file and registers the style in `block.json`.

```html
<section data-style="style.css"></section>
```

--------------------------------

### Import Global Stylesheet in Block's JS

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/styles-and-scripts.mdx

This JavaScript snippet shows how a global stylesheet is imported into the block's main JavaScript file. The imported CSS file is processed by webpack and registered in `block.json`.

```jsx
import { registerBlockType } from "@wordpress/blocks";

// highlight-next-line
import "./style.css";

import Edit from "./edit.js";
import metadata from "./block.json";

registerBlockType(metadata.name, {
  edit: Edit,
  save: () => null,
});
```

--------------------------------

### Bind HTML to Block Attributes

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Use `data-bind` attributes in HTML to link elements to block attributes. Default values can be specified directly in the HTML.

```html
<!-- src/my-block.html -->
<section>
  <!-- string attribute "sectionTitle", default value "Section title" -->
  <h2 data-bind="sectionTitle">Section title</h2>

  <!-- string attribute "sectionDescription" -->
  <p data-bind="sectionDescription">Description</p>

  <!-- boolean attribute "isChecked" -->
  <input type="checkbox" data-bind="isChecked" />

  <!-- integer attribute "sectionImage" — triggers MediaUpload in edit.js -->
  <img data-bind="sectionImage" />

  <!-- iframe src bound to a string attribute -->
  <iframe data-bind="videoUrl"></iframe>
</section>
```

--------------------------------

### HTMLToGutenberg Programmatic API Usage

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Utilize the `HTMLToGutenberg` class for integrating the compiler into non-Webpack toolchains. Reads HTML, compiles it, and writes generated files.

```javascript
import HTMLToGutenberg from "@jverneaut/html-to-gutenberg/src/HTMLToGutenberg.js";
import processors from "@jverneaut/html-to-gutenberg/src/processors/index.js";
import printers   from "@jverneaut/html-to-gutenberg/src/printers/index.js";
import fs from "fs/promises";

const compiler = new HTMLToGutenberg({
  printers,
  processors,
  defaultNamespace: "custom",
  defaultCategory:  "theme",
  defaultVersion:   "0.1.0",
  defaultIcon:      null,
});

const htmlContent = await fs.readFile("./src/hero.html", "utf-8");

const result = await compiler.printBlockFromHTMLFileContent(htmlContent, {
  name:       "custom/hero",
  textdomain: "hero",
  title:      "Hero",
});

// result.files = { "edit.js": "…", "render.php": "…", "block.json": "…", "index.js": "…" }
// result.dependencies = […]  (npm packages needed by the block)

for (const [filename, content] of Object.entries(result.files)) {
  await fs.writeFile(`./generated-blocks/hero/${filename}`, content);
}
```

--------------------------------

### Add View Script to Block

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/styles-and-scripts.mdx

Use the `data-view-script` attribute in your HTML to specify a JavaScript file that will be loaded on the frontend for the block. This adds an entry to your webpack configuration and registers the script in `block.json`.

```html
<section data-view-script="viewScript.js"></section>
```

--------------------------------

### Gutenberg Block Editor JavaScript Component

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/common/_example.md

Implements the editor interface for a Gutenberg block using React and WordPress components. Use this to define how the block appears and behaves within the WordPress editor, including dynamic content and settings.

```jsx
import {
  useBlockEditingMode,
  InnerBlocks,
  RichText,
  MediaUpload,
  InspectorControls,
} from "@wordpress/block-editor";
import { PanelBody, SelectControl } from "@wordpress/components";
import { Image } from "@10up/block-components/components/image";

export default ({ attributes, setAttributes }) => {
  useBlockEditingMode("contentOnly");

  return (
    <section {...useBlockProps({ className: "py-20 bg-blue-200" })}>
      <InspectorControls>
        <PanelBody title="Settings">
          <SelectControl
            label="Post Type"
            value={attributes.postType}
            onChange={(postType) => setAttributes({ postType })}
            options={[
              { label: "Posts", value: "posts" },
              { label: "Pages", value: "pages" },
            ]}
          ></SelectControl>
        </PanelBody>
      </InspectorControls>

      <div className="container">
        <div className="grid grid-cols-12 gap-4">
          <div className="col-span-12 md:col-span-6">
            <RichText
              className="text-2xl"
              tagName="h2"
              value={attributes.sectionTitle}
              onChange={(sectionTitle) => setAttributes({ sectionTitle })}
              placeholder="Section title"
            ></RichText>
            <MediaUpload
              value={attributes.sectionImage}
              onSelect={(image) => setAttributes({ sectionImage: image.id })}
              render={({ open }) => (
                <Image
                  style={{ cursor: "pointer", pointerEvents: "all" }}
                  onClick={open}
                  className="aspect-square object-cover"
                  id={attributes.sectionImage}
                  onSelect={(image) =>
                    setAttributes({ sectionImage: image.id })
                  }
                />
              )}
            ></MediaUpload>
          </div>

          <div className="col-span-12 md:col-span-6">
            <InnerBlocks
              template={[
                [
                  "core/group",
                  {},
                  [
                    ["core/heading", { level: 3 }],
                    [
                      "core/paragraph",
                      { content: "Lorem ipsum dolor sit amet consectetur." },
                    ],
                  ],
                ],
              ]}
              templateLock="all"
            ></InnerBlocks>
          </div>
        </div>
      </div>
    </section>
  );
};
```

--------------------------------

### Binding Post Title with data-bind

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/data-binding.mdx

Bind to the post title using `data-bind="post.title"` to display and edit the post's title directly within an element.

```html
<section class="hero">
    <!-- Displays and edits the post title -->
    <h1 class="hero__title" data-bind="post.title"></h1>
  </section>
```

--------------------------------

### Registering Blocks in WordPress

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

This PHP code snippet demonstrates how to register generated Gutenberg blocks within your WordPress theme's `functions.php` file or a custom plugin. Ensure the path points to the compiled build output.

```php
// functions.php (theme) or a custom plugin
add_action('init', function () {
    $blocks_path = get_stylesheet_directory() . '/dist/blocks';
    $blocks = array_filter(glob($blocks_path . '/**/*'), 'is_dir');

    foreach ($blocks as $block) {
        register_block_type($block);   // points at compiled build output, not generated-blocks/
    }
});
```

--------------------------------

### Render Gutenberg Block Content in PHP

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/common/_example.md

This PHP code snippet defines the rendering logic for a Gutenberg block. It retrieves attributes for a section image and title, then outputs HTML structure with dynamic content and styling. Use this for server-side rendering of block content.

```php
<?php

$sectionImage_id = $attributes['sectionImage'] ?? '';
$sectionImage = $sectionImage_id ? wp_get_attachment_image_src($sectionImage_id, 'full') : [''];
$sectionImage_src = $sectionImage[0] ?? '';
$sectionImage_srcset = $sectionImage_id ? wp_get_attachment_image_srcset($sectionImage_id, 'full') : '';
$sectionImage_sizes = $sectionImage_id ? wp_get_attachment_image_sizes($sectionImage_id, 'full') : '';
$sectionImage_alt = $sectionImage_id ? get_post_meta($sectionImage_id, '_wp_attachment_image_alt', true) : '';

?>

<section <?php echo get_block_wrapper_attributes(['class' => 'py-20 bg-blue-200']); ?> >
  <div class="container">
    <div class="grid grid-cols-12 gap-4">
      <div class="col-span-12 md:col-span-6">
        <h2 class="text-2xl"><?php echo wp_kses_post($attributes['sectionTitle'] ?? ''); ?></h2>
        <img class="aspect-square object-cover" src="<?php echo esc_url($sectionImage_src); ?>" srcset="<?php echo esc_attr($sectionImage_srcset); ?>" sizes="<?php echo esc_attr($sectionImage_sizes); ?>" alt="<?php echo esc_attr($sectionImage_alt); ?>" />
      </div>
      <div class="col-span-12 md:col-span-6">
        <?php echo $content; ?>
      </div>
    </div>
  </div>
</section>
```

--------------------------------

### Creating Complex Compositions with Nested InnerBlocks

Source: https://github.com/jverneaut/html-to-gutenberg/blob/main/docs/docs/guides/inner-blocks.mdx

Nest templates within <inner-blocks> to create complex compositions, similar to nesting HTML elements.

```html
<section>
  <inner-blocks>
    <inner-block name="core/group">
      <inner-block name="core/heading"></inner-block>
      <inner-block name="core/paragraph"></inner-block>
    </inner-block>
  </inner-blocks>
</section>
```

--------------------------------

### Register Post Meta for REST API

Source: https://context7.com/jverneaut/html-to-gutenberg/llms.txt

Register custom post meta fields using `register_post_meta` with `show_in_rest` set to `true` to enable editing in the block editor.

```php
// Register meta so it is editable via the REST API
register_post_meta('recipe', 'cooking_time', [
    'show_in_rest' => true,
    'single'       => true,
    'type'         => 'string',
]);
```