How to Convert Existing Page Layouts into Block Patterns for Theme Distribution

Why Converting Existing Layouts to Block Patterns Makes Strategic Sense

Every established WordPress theme and agency has a library of page layouts that have been refined through real client projects. These layouts represent proven design decisions backed by actual user feedback and conversion data. Converting them into block patterns extracts that accumulated design wisdom and packages it in a format that the block editor natively understands, making it available to every user of your theme without any additional plugins or configuration.

The conversion process is not simply copying HTML into a pattern file. It requires understanding how block markup differs from traditional HTML, how to handle dynamic elements that depend on server-side data, and how to structure patterns for portability across different WordPress installations. A layout that worked perfectly as a custom page template may need significant restructuring to function correctly as a block pattern.

This guide provides a complete methodology for extracting layouts from existing pages, cleaning them up for pattern compatibility, handling edge cases around dynamic content and media, and ultimately submitting polished patterns to the WordPress Pattern Directory for community distribution. Whether your source material is a classic theme template, a page builder layout, or a hand-coded block editor page, the principles covered here apply.

Identifying Layouts Worth Converting

Not every page layout deserves to become a block pattern. The best candidates share certain characteristics that make them valuable as reusable starting points. Evaluating your existing layouts against these criteria helps prioritize your conversion effort.

Universality: Layouts that serve common purposes (landing pages, about pages, contact pages, pricing pages) have the broadest appeal. A highly specialized layout for a single client’s unique business process is unlikely to be useful to others.

Visual completeness: Patterns should look polished immediately upon insertion. Layouts that depend heavily on custom CSS, JavaScript animations, or specific image dimensions may not translate well to patterns where users will substitute their own content.

Block compatibility: Layouts built primarily with standard WordPress blocks convert more easily than those relying on custom HTML, shortcodes, or plugin-specific blocks. If a layout uses a third-party slider plugin, that dependency becomes a barrier for pattern users who do not have the same plugin installed.

Design system alignment: Layouts that follow your theme’s design token system convert with less friction. If a layout uses colors, fonts, and spacing that are already defined in your theme.json configuration, the resulting pattern will automatically inherit those values. Layouts with ad-hoc styling require more cleanup work.

Create an inventory of your existing layouts and score each one on these four criteria. Prioritize the highest-scoring layouts for conversion first. This gives you the best return on your conversion effort while you refine your process.

Extracting Block Markup from Existing Pages

The first step in converting a layout is extracting its block markup. The approach depends on how the layout was originally built.

Extracting from Block Editor Pages

If the layout was built in the block editor, extraction is straightforward. Open the page in the editor, switch to the Code Editor view (accessible from the three-dot menu in the top-right corner), and copy the raw block markup. This markup includes the block comment delimiters, attributes, and HTML content that WordPress uses to render each block.

Here is an example of raw block markup from a typical hero section:

<!-- wp:cover {"url":"https://example.com/wp-content/uploads/hero-bg.jpg","dimRatio":60,"overlayColor":"black","minHeight":650,"align":"full"} -->
<div class="wp-block-cover alignfull" style="min-height:650px">
  <span aria-hidden="true" class="wp-block-cover__gradient-background has-black-background-color has-background-dim-60 has-background-dim"></span>
  <img class="wp-block-cover__image-background" alt="" src="https://example.com/wp-content/uploads/hero-bg.jpg" data-object-fit="cover"/>
  <div class="wp-block-cover__inner-container">
    <!-- wp:heading {"textAlign":"center","level":1,"textColor":"white"} -->
    <h1 class="has-text-align-center has-white-color has-text-color">Welcome to Our Platform</h1>
    <!-- /wp:heading -->
    <!-- wp:paragraph {"align":"center","textColor":"white"} -->
    <p class="has-text-align-center has-white-color has-text-color">We help businesses grow with modern solutions.</p>
    <!-- /wp:paragraph -->
  </div>
</div>
<!-- /wp:cover -->

This raw markup serves as your starting material for the cleanup process described in the following sections.

Extracting from Classic Theme Templates

Classic theme templates use PHP and HTML without block markup. Converting these layouts requires rebuilding the design using block editor blocks. There is no automated tool that converts arbitrary PHP templates into block markup because the semantic intent of custom PHP code cannot be reliably inferred.

The practical approach is to use the classic template as a visual reference and rebuild the layout in the block editor from scratch. Open the template in a browser, identify the major sections (header, hero, content areas, sidebars, footer), and recreate each section using appropriate blocks. This manual process has the benefit of producing clean, modern markup that leverages the latest block editor features.

For complex layouts with many sections, break the conversion into multiple patterns rather than attempting to create a single full-page pattern. A full-page template might become five or six individual section patterns that users can combine in any order.

Extracting from Page Builder Layouts

Page builder plugins (Elementor, Beaver Builder, Divi, WPBakery) store layout data in proprietary formats. These formats are not compatible with block patterns, and there is no reliable conversion path from page builder data to block markup. Like classic templates, the practical approach is visual recreation.

Export or screenshot the page builder layout, then rebuild it section by section in the block editor. Focus on matching the visual design and content structure rather than replicating every animation and interactive effect, as block patterns support a different set of capabilities than page builders.

Cleaning Up Pattern Markup for Portability

Raw block markup extracted from an existing page contains installation-specific data that must be cleaned before the markup can function as a portable pattern. This cleanup process is the most critical step in the conversion workflow.

Remove Absolute URLs

Existing pages contain absolute URLs pointing to the source WordPress installation’s domain. Image URLs, link URLs, and any other references to https://example.com/wp-content/... must be replaced. For images, use the PHP approach with get_template_directory_uri() or replace with appropriate placeholder references. For links, replace them with generic placeholders like # or remove them entirely.

<!-- Before cleanup: -->
<!-- wp:image {"id":1234,"sizeSlug":"large"} -->
<figure class="wp-block-image size-large">
  <img src="https://example.com/wp-content/uploads/2024/03/hero-image.jpg" alt="Hero" class="wp-image-1234"/>
</figure>
<!-- /wp:image -->

<!-- After cleanup: -->
<!-- wp:image {"sizeSlug":"large"} -->
<figure class="wp-block-image size-large">
  <img src="<?php echo esc_url( get_template_directory_uri() . '/assets/images/patterns/hero-placeholder.webp' ); ?>" alt="<?php esc_attr_e( 'Hero section placeholder', 'my-theme' ); ?>"/>
</figure>
<!-- /wp:image -->

Notice that the id attribute was also removed. Attachment IDs are specific to the source installation and will not correspond to any media item on the destination site.

Remove Installation-Specific Attributes

Several block attributes contain installation-specific data that should be stripped during cleanup:

Attachment IDs: The id attribute on image blocks, gallery blocks, and media-text blocks references the WordPress media library ID of a specific installation. Remove these attributes entirely.

Post IDs: Query blocks and post-related blocks may reference specific post or category IDs. Replace these with generic queries that work on any installation.

User IDs: Author blocks or any blocks that reference specific users should have their user references removed or generalized.

Custom CSS classes: If the source page used custom CSS classes that were defined in the theme’s stylesheet, verify that these classes exist in the pattern’s theme as well. Remove any classes that are specific to the source installation’s custom CSS.

Replace Hard-Coded Styles with Theme Presets

Extracted markup often contains hard-coded color values, font sizes, and spacing values. Replace these with references to your theme.json presets wherever possible. This is the most labor-intensive part of the cleanup process but yields the most maintainable result.

<!-- Before: hard-coded values -->
<!-- wp:group {"style":{"color":{"background":"#1a1a2e","text":"#ffffff"},"spacing":{"padding":{"top":"80px","bottom":"80px","left":"40px","right":"40px"}},"typography":{"fontSize":"18px"}}} -->

<!-- After: theme.json presets -->
<!-- wp:group {"backgroundColor":"contrast","textColor":"base","style":{"spacing":{"padding":{"top":"var:preset|spacing|70","bottom":"var:preset|spacing|70","left":"var:preset|spacing|50","right":"var:preset|spacing|50"}}},"fontSize":"medium"} -->

This replacement process requires you to know the preset slugs defined in your theme.json. Maintain a reference sheet of your theme’s available presets (color names, spacing scale values, font size slugs) to streamline this step. For more detail on structuring these presets effectively, see our guide on block pattern collections.

Validate Block Markup Integrity

After cleanup, validate that the block markup is structurally correct. Every opening block comment must have a corresponding closing comment. The JSON in block attributes must be valid. The HTML structure within each block must match what WordPress expects.

The simplest validation method is to paste the cleaned markup into a new page in the block editor and check for block validation errors. The editor displays a warning when it encounters markup that does not match the expected structure for a block. Fix any validation errors before proceeding.

WordPress provides a block validation mechanism that compares the stored markup against the block’s expected output. When there is a mismatch, the editor offers to attempt block recovery or lets the user convert to a Classic block. A well-cleaned pattern should insert without triggering any validation warnings.

Handling Dynamic Content in Patterns

Dynamic content presents the biggest challenge when converting layouts to patterns. Layouts that display recent posts, user information, WooCommerce products, or other data-driven content require careful handling because patterns are static snapshots that get copied into user content.

Query Blocks for Post-Based Content

The Query Loop block provides a pattern-compatible way to display dynamic post content. Unlike custom PHP queries, the Query Loop block stores its parameters as block attributes, which means the query configuration travels with the pattern when it is inserted.

<!-- wp:query {"queryId":0,"query":{"perPage":3,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":false}} -->
<div class="wp-block-query">
  <!-- wp:post-template {"layout":{"type":"grid","columnCount":3}} -->
    <!-- wp:post-featured-image {"isLink":true,"aspectRatio":"16/9"} /-->
    <!-- wp:post-title {"isLink":true,"level":3} /-->
    <!-- wp:post-excerpt {"excerptLength":20} /-->
    <!-- wp:post-date /-->
  <!-- /wp:post-template -->
  <!-- wp:query-pagination -->
    <!-- wp:query-pagination-previous /-->
    <!-- wp:query-pagination-numbers /-->
    <!-- wp:query-pagination-next /-->
  <!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

When converting a layout that uses a custom WP_Query loop in PHP, rebuild it using the Query Loop block. The block supports filtering by post type, category, tag, author, and other common query parameters. For queries that exceed the block’s built-in capabilities, you may need to accept a simpler query or create a custom block that handles the specific query requirements.

Site-Level Dynamic Blocks

WordPress provides several dynamic blocks that render server-side content based on the current site’s configuration. These blocks work perfectly in patterns because they query live data at render time rather than storing static content. The key site-level dynamic blocks include:

Site Title (core/site-title) renders the site name from Settings. Site Logo (core/site-logo) renders the configured site logo. Navigation (core/navigation) renders the assigned navigation menu. Login/Logout (core/loginout) renders context-appropriate authentication links.

Use these dynamic blocks in header and footer patterns to ensure the pattern adapts to each site’s configuration. A header pattern that uses the Site Logo and Navigation blocks will display the correct logo and menu on any site that activates the theme.

Content That Cannot Be Dynamic

Some content types have no block-based equivalent. Custom fields displayed through Advanced Custom Fields, WooCommerce product grids, BuddyPress member directories, and other plugin-specific content cannot be represented in block patterns without creating a plugin dependency. For these cases, use placeholder content in the pattern and add a clear description in the pattern metadata explaining that users need to replace the placeholder with their specific content source.

Image and Media Handling in Patterns

Media handling requires attention because images are the most visible element of any pattern, yet they are also the most installation-specific. Your strategy for handling media affects both the quality of the user experience and the technical portability of the pattern.

Bundled Placeholder Images

The most common approach for theme-distributed patterns is to bundle optimized placeholder images in the theme’s assets directory. These images demonstrate the pattern’s intended layout and visual feel while being generic enough that users understand they should replace them.

Guidelines for placeholder images:

Keep each image under 200KB. Use WebP format for best compression. Choose images that are visually neutral (abstract textures, muted photographs, simple illustrations) so they do not clash with any brand. Provide images at the dimensions your pattern expects to avoid layout shifts. Include meaningful alt text that describes the placeholder purpose, not the placeholder image itself.

Organize placeholder images in a dedicated directory within your theme:

my-theme/
  assets/
    images/
      patterns/
        hero-bg-light.webp
        hero-bg-dark.webp
        team-member-1.webp
        team-member-2.webp
        team-member-3.webp
        testimonial-avatar.webp
        product-placeholder.webp

Using CSS Backgrounds Instead of Images

For decorative backgrounds, CSS gradients and solid colors eliminate the need for image files entirely. The Cover block supports gradient backgrounds, and Group blocks support background colors. Patterns that use these CSS-based approaches are lighter, faster loading, and easier to customize.

<!-- CSS gradient instead of an image -->
<!-- wp:cover {"gradient":"cool-to-warm-spectrum","minHeight":500,"align":"full"} -->
<div class="wp-block-cover alignfull" style="min-height:500px">
  <span aria-hidden="true" class="wp-block-cover__gradient-background has-cool-to-warm-spectrum-gradient-background"></span>
  <div class="wp-block-cover__inner-container">
    <!-- Pattern content here -->
  </div>
</div>
<!-- /wp:cover -->

Define custom gradients in your theme.json file and reference them by slug in your patterns. This approach lets users customize the gradient through the Site Editor’s Global Styles panel.

SVG and Icon Handling

Patterns that use icons for feature lists, service descriptions, or navigation benefit from inline SVG or icon font references. WordPress does not natively support SVG uploads in the media library, so inline SVG within block markup is the most reliable approach for patterns.

Use the Custom HTML block to embed inline SVG icons within your patterns. While this approach is less elegant than using a dedicated icon block, it avoids plugin dependencies and works on every WordPress installation.

Structuring Patterns for Full-Page Layouts

Some converted layouts represent complete pages rather than individual sections. Full-page patterns are valuable for users who want to create common page types (About, Contact, Services, Pricing) with a single insertion. However, they require careful structuring to work well in the editor.

Section-Based Organization

Organize full-page patterns as a series of clearly delineated sections using Group blocks with full-width alignment. Each section should be an independent Group block that users can move, delete, or modify without affecting other sections.

<!-- Section 1: Hero -->
<!-- wp:group {"align":"full","backgroundColor":"primary","style":{"spacing":{"padding":{"top":"var:preset|spacing|80","bottom":"var:preset|spacing|80"}}}} -->
<div class="wp-block-group alignfull has-primary-background-color has-background" style="padding-top:var(--wp--preset--spacing--80);padding-bottom:var(--wp--preset--spacing--80)">
  <!-- Hero content -->
</div>
<!-- /wp:group -->

<!-- Section 2: Features -->
<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"var:preset|spacing|70","bottom":"var:preset|spacing|70"}}}} -->
<div class="wp-block-group alignfull" style="padding-top:var(--wp--preset--spacing--70);padding-bottom:var(--wp--preset--spacing--70)">
  <!-- Features content -->
</div>
<!-- /wp:group -->

<!-- Section 3: Testimonials -->
<!-- wp:group {"align":"full","backgroundColor":"secondary","style":{"spacing":{"padding":{"top":"var:preset|spacing|70","bottom":"var:preset|spacing|70"}}}} -->
<div class="wp-block-group alignfull has-secondary-background-color has-background" style="padding-top:var(--wp--preset--spacing--70);padding-bottom:var(--wp--preset--spacing--70)">
  <!-- Testimonials content -->
</div>
<!-- /wp:group -->

This section-based approach means that even within a full-page pattern, users can rearrange sections, delete sections they do not need, or insert additional patterns between existing sections. The pattern serves as a flexible starting point rather than a rigid template.

Offering Both Full-Page and Section Patterns

For maximum flexibility, consider shipping both the full-page pattern and its individual sections as separate patterns. A “Services Page” full-page pattern could be accompanied by standalone “Services Hero,” “Services Feature Grid,” “Services Testimonials,” and “Services CTA” patterns. Users who want the complete page use the full-page pattern, while users who just need a feature grid section can use the standalone version.

Mark the standalone section patterns with the Inserter: yes header so they appear in the pattern inserter. You can optionally mark the full-page pattern with its own category (like mytheme-pages) to separate complete pages from individual sections in the inserter interface.

Converting Responsive Layouts

Responsive behavior in block patterns relies primarily on the theme’s CSS and the block editor’s built-in responsive handling. Unlike page builders, which provide granular per-breakpoint controls, the block editor handles responsive layout through the block’s own CSS and the theme’s stylesheet.

The Columns block automatically stacks on narrow viewports. The Group block with flex layout wraps items naturally. The Cover block adjusts its content positioning based on available space. These built-in behaviors handle most responsive scenarios without additional CSS.

For layouts that need specific responsive behavior beyond the defaults, you have two options: add custom CSS to your theme’s stylesheet that targets the block’s generated class names, or use the block’s built-in layout system to create naturally responsive structures.

When converting layouts that had complex responsive behavior, simplify the design for the pattern version. A three-column layout that had custom breakpoints at 600px, 900px, and 1200px in the original CSS might work better as a standard Columns block that relies on the editor’s default stacking behavior. The slight loss in responsive precision is usually an acceptable trade-off for the significant gain in portability and maintainability.

Testing Converted Patterns Thoroughly

Converted patterns require more thorough testing than patterns built from scratch because the conversion process can introduce subtle issues. Follow a systematic testing protocol that covers the major failure modes.

Insertion test: Insert the pattern into a new page and verify that no block validation errors appear. Check both the visual editor and the code editor to confirm the markup is clean.

Content editing test: Edit the text content within the inserted pattern. Change headings, paragraphs, and button labels. Verify that the visual layout remains intact after edits. Some block structures can shift unexpectedly when content length changes significantly.

Media replacement test: Replace all placeholder images with different images of varying aspect ratios. Verify that the layout handles different image proportions gracefully. Test with both landscape and portrait images to catch aspect ratio assumptions in the markup.

Color and style test: Switch between your theme’s style variations (if available) and verify that the pattern looks correct in each variation. Patterns that use hard-coded color values will fail this test, revealing cleanup work that was missed.

Front-end test: View the page on the front end and compare it to the editor view. Some blocks render differently on the front end, especially blocks that use server-side rendering. Verify that the final output matches expectations.

Mobile test: Check the pattern at 390px viewport width. Verify that text is readable, images scale correctly, columns stack properly, and interactive elements (buttons, links) are tappable at mobile sizes. Patterns that look great on desktop but break on mobile are not ready for distribution.

Submitting Patterns to the WordPress Pattern Directory

The WordPress.org Pattern Directory is a public repository where any WordPress user can browse, preview, and copy patterns. Submitting your best patterns to the directory increases your visibility as a developer, provides a service to the community, and generates feedback that improves your design skills.

Requirements for Directory Submission

The Pattern Directory accepts patterns that use only core blocks. No third-party block dependencies are allowed. The pattern must work on any WordPress installation with any theme, which means it cannot rely on theme-specific presets, custom CSS, or custom block styles.

This requirement means that patterns you submit to the directory will be different from patterns you bundle with your theme. Theme-bundled patterns can use your theme.json presets; directory patterns must use universal values. You may need to create two versions of the same pattern: one optimized for your theme and one generalized for the directory.

Submission Process

To submit a pattern, visit the Gutenberg developer documentation for the current submission guidelines. The process typically involves creating the pattern in a special submission editor on WordPress.org, assigning appropriate categories and keywords, and submitting it for review. The review team checks for markup quality, visual appeal, and adherence to the submission guidelines.

Patterns with clean, well-organized markup are more likely to pass review quickly. Avoid deeply nested structures, unnecessary wrapper blocks, and inline styles that could be replaced with block-level settings. The review team looks for patterns that represent best practices in block markup.

Maintaining Directory Patterns

After submission, monitor your patterns for user feedback and compatibility issues. WordPress core updates occasionally change block markup formats or introduce new block features. Patterns that use deprecated markup may need updates to maintain visual fidelity. The Pattern Directory provides analytics that show how often your patterns are being copied, which helps prioritize maintenance effort.

Automating the Conversion Workflow

If you have many layouts to convert, building a semi-automated workflow saves significant time. While full automation is not possible due to the design judgment required, several steps can be scripted.

URL replacement: Write a script that scans block markup for absolute URLs matching your source domain and replaces them with the PHP template directory URI function. This handles the most tedious part of the cleanup process.

#!/bin/bash
# Simple URL replacement script for pattern cleanup
SOURCE_DOMAIN="https://example.com/wp-content/uploads"
REPLACEMENT=''

find ./patterns -name "*.php" -exec sed -i '' "s|${SOURCE_DOMAIN}[^\"]*|${REPLACEMENT}|g" {} +

ID stripping: Write a regex replacement that removes attachment IDs, post IDs, and user IDs from block attributes. This can be done with a find-and-replace across all pattern files.

Metadata generation: Create a template for the pattern metadata header and use a script to prepend it to pattern files. The script can accept parameters for title, slug, and categories, reducing the manual work of writing headers for each pattern.

Validation: Use the WordPress block parser (available as a JavaScript package via @wordpress/block-serialization-default-parser) to validate your pattern markup programmatically. This catches structural errors before you test in the editor.

Organizing Converted Patterns in Your Theme

As converted patterns accumulate, maintain clear organization to prevent the pattern library from becoming unwieldy. Use a naming convention that indicates the pattern’s origin and purpose.

A recommended naming scheme for converted patterns:

patterns/
  # Section patterns (individual sections)
  hero-centered-light.php
  hero-split-image-right.php
  features-three-column-icons.php
  testimonials-grid-cards.php
  cta-banner-gradient.php
  footer-four-column-dark.php

  # Full-page patterns
  page-about-company.php
  page-services-agency.php
  page-pricing-three-tier.php
  page-contact-form.php

  # Template part patterns
  header-logo-nav-cta.php
  header-centered-minimal.php
  footer-sitemap-newsletter.php

This naming convention makes it immediately clear whether a pattern is a section, a full page, or a template part. The descriptive suffixes help developers locate specific patterns without opening each file.

Common Conversion Challenges and Solutions

Certain layout elements consistently present challenges during conversion. Understanding these challenges in advance helps you plan your approach.

Multi-column layouts with unequal widths: The Columns block supports percentage-based width settings for individual columns, but the syntax in block markup can be tricky. Set column widths explicitly in the block attributes to ensure the layout renders correctly.

Overlapping elements: Traditional CSS layouts often use absolute positioning to create overlapping elements. The block editor does not support arbitrary positioning, so overlapping designs need to be reimagined using Cover blocks, negative margins (where supported), or simplified to non-overlapping alternatives.

Custom fonts: Layouts that use fonts not available in the theme’s typography stack need their font references updated. Use the font family presets from your theme.json rather than hard-coding font names.

Animation and interactivity: CSS animations, scroll effects, and JavaScript interactivity cannot be represented in block patterns. Converted patterns should focus on the static layout and typography. If interactivity is essential, consider creating a custom block rather than a pattern.

Form layouts: Contact forms and other interactive forms require a form plugin. Patterns that include forms must document this dependency. The simplest approach is to include a placeholder paragraph in the pattern that instructs users to insert their preferred form block.

Measuring the Impact of Your Pattern Library

After launching your converted pattern library, measure its impact on user satisfaction and theme adoption. While direct analytics on pattern usage within a theme are limited, several indirect metrics provide useful signals.

Support ticket volume related to page building should decrease if your patterns are genuinely useful. Track support tickets that ask “how do I create [specific layout]” before and after adding patterns that address those layouts.

Theme review ratings on WordPress.org often mention patterns specifically. Monitor reviews for mentions of patterns, layouts, and design options to understand how users perceive your library.

If you submit patterns to the WordPress.org Pattern Directory, the directory provides copy counts that show how popular each pattern is. Use these metrics to guide future pattern development, creating more patterns in the categories that users find most valuable.

Conclusion

Converting existing page layouts into block patterns is a practical way to leverage proven designs within the modern WordPress editing experience. The process requires attention to markup cleanup, media handling, dynamic content management, and thorough testing, but the result is a pattern library that dramatically improves the user experience for anyone building pages with your theme. Start with your most popular and versatile layouts, refine your conversion process with each pattern, and expand your library based on user feedback and usage data. The investment in conversion pays dividends through reduced support burden, improved theme ratings, and a stronger competitive position in the theme marketplace.