Code Converter Guide

The Draft Layout Code Converters take source code files as input (HTML/PHP with Tailwind classes) and output a format that's editable in WordPress drag/drop visual editors.

Gutenberg/Block Editor

The Gutenberg Code Converter is in beta. Please try it out, and if you have any feedback, suggestions, or issues, email me at [email protected].

Setup

For WordPress's default Block Editor, you first need to decide which design tokens (like colors, spacing, font sizes/families) you want to use.

You'll need to specify them in your WP theme's theme.json file:

{
  "$schema": "https://schemas.wp.org/wp/6.7/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "color": "#ffffff", "name": "White", "slug": "white" },
        { "color": "#b91c1c", "name": "Red 700", "slug": "red-700" }
      ]
    },
    "spacing": {
      "spacingSizes": [
        { "name": "1", "size": "0.25rem", "slug": "1" },
        { "name": "4", "size": "1rem", "slug": "4" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "name": "sm", "size": "0.875rem", "slug": "sm", "fluid": false },
        { "name": "xl", "size": "1.25rem", "slug": "xl", "fluid": false }
      ],
      "fontFamilies": [
        { "name": "Serif", "slug": "serif", "fontFamily": "Aleo, serif", "fontFace": [...] }
      ]
    }
  }
}

For the example above, you can use Tailwind classes like .bg-white or .border-red-700, and they'll map to their corresponding values specified in your theme.json, and those are the options that will be pre-selected in the Block Editor UI.

Similarly, you can use spacing tokens (.p-1, .mb-4), font sizes (.text-sm), and font families (.font-serif).

If you want a theme.json template that already has all the default Tailwind colors, spacing, and fonts defined, here's one you can modify and use:

https://draftlayout.com/examples/theme.json

Workflow

In the WP theme's source code, define a directory that'll contain all the Tailwind HTML/PHP code. Let's say that's ./src.

Then start the CLI tool:

$ dl-block -i ./src -o ./
# -i, --inputDir: your Tailwind code directory
# -o, --outputDir: where you want the converted files to be placed

Now, if you create a file ./src/patterns/header.php containing Tailwind classes, dl-block will watch that file for changes and output the converted file (containing WP Block syntax) to ./patterns/header.php.

You can now select this Block Pattern inside Gutenberg's visual editor to see the layout you've built!

PHP Syntax Support

The Converter will watch files ending in .html and .php inside the --inputDir you specified.

While HTML files work fine, there are some cases where PHP parsing may fail.

PHP tags (<?php ?>) inside an HTML element's attribute value should work. But they work best when they don't break up individual HTML tags.

If you encounter a problem, try wrapping PHP tags with HTML comments (<!-- <?php ... ?> -->). The Converter should remove the comments while preserving the PHP code.

Supported Tailwind classes

Flexbox

flex flex-nowrap flex-col
basis-0 basis-full basis-x/y (e.g. basis-1/12, basis-4/5)
justify-start justify-center justify-end justify-between
items-start items-center items-end items-stretch
gap-*

Spacing

m-* mt-* mb-* ml-* mr-* mx-* my-*
p-* pt-* pb-* pl-* pr-* px-* py-*

Text, borders, backgrounds

text-* font-*
border-* rounded-*
bg-*

text-* classes support CSS text-align (right, center, and left), CSS color (e.g. text-red-500), and CSS font-size (e.g. text-sm).

bg-* classes only support CSS background-color.

font-* classes support CSS font-weight (like font-bold, font-thin) and font-family.

border-* classes support CSS border-color (like border-slate-300) and border-width (e.g. border-px, border-2).

rounded-* classes support Tailwind defaults (like rounded-sm, rounded-xl).

WordPress-specific

a-full: Align Full

a-wide: Align Wide

l-constrained: Layout Constrained

cs-*: Content Size (like cs-600px)

ws-*: Wide Size (like ws-1200px)

WordPress Columns Block:

By default, Columns stack/wrap to the next line; use .cols-nostack to disable this. Use .basis-x/y classes to specify a percentage width.

<div class="cols cols-nostack">
  <div class="basis-4/12">...</div>
  <div class="basis-8/12">...</div>
</div>

WordPress Buttons Block:

Due to WP's Block syntax, you can't have a single button on its own. It needs to be wrapped in .btns and .btn classes.

<div class="btns">
  <div class="btn">
    <a class="btn-link">Contact Us</a>
  </div>
</div>

WordPress Images:

Due to WP's Block syntax, you need to wrap <img> tags with <figure>.

<figure>
  <img src="..." alt="..." />
</figure>