/wp-classic-to-fse

description: Convert an existing classic WordPress theme (PHP templates, functions.php) into a Full Site Editing block theme.

/wp-classic-to-fse

**Purpose:** Convert an existing classic WordPress theme (PHP template files, `functions.php`, `style.css`) into a Full Site Editing (FSE) block theme, preserving the visual design and site structure.

When to Use

This command is specifically for users who already have a **WordPress classic theme** (one with `header.php`, `footer.php`, `index.php`, `single.php`, etc.) and want to convert it to a block theme.

• **Use this command** when the source is an existing WordPress classic theme
• **Use `/convert-to-wp-theme`** when the source is static HTML/CSS/JS (non-WordPress)
• **Use `/wp-migrate`** when the user wants to migrate content (posts, widgets, ACF) rather than the theme files themselves

Workflow

Step 1: Audit the Classic Theme

Ask the user to provide:

1. The theme's `style.css` (header metadata) 2. List of PHP template files present 3. `functions.php` (or key sections of it) 4. Any CSS files and their structure 5. Whether any page builders (Elementor, Divi) are being used on top of the classic theme

From these, identify:

CLASSIC THEME AUDIT
====================
Theme name:    {{Classic Theme Name}}
Template files: {{list of .php files}}
Style:          {{CSS methodology — BEM, utility, custom?}}
Plugins used:  {{list active plugins affecting display}}
Dynamic areas: {{sidebars, widget areas, nav menus}}
Custom functionality: {{shortcodes, custom post types, custom queries}}
JavaScript:    {{enqueued scripts and their purpose}}

Step 2: Mapping — Classic to FSE

Map each classic theme file to its FSE equivalent:

| Classic File | FSE Equivalent | Notes | |-------------|----------------|-------| | `header.php` | `parts/header.html` | Convert PHP to block markup | | `footer.php` | `parts/footer.html` | Convert PHP to block markup | | `sidebar.php` | `parts/sidebar.html` | Widget areas → blocks | | `index.php` | `templates/index.html` | | | `home.php` | `templates/home.html` | Blog home page | | `front-page.php` | `templates/front-page.html` | Static front page | | `page.php` | `templates/page.html` | | | `single.php` | `templates/single.html` | | | `single-{{cpt}}.php` | `templates/single-{{cpt}}.html` | Per CPT | | `archive.php` | `templates/archive.html` | | | `archive-{{cpt}}.php` | `templates/archive-{{cpt}}.html` | Per CPT | | `category.php` | `templates/category.html` | | | `tag.php` | `templates/tag.html` | | | `taxonomy-{{tax}}.php` | `templates/taxonomy-{{tax}}.html` | | | `search.php` | `templates/search.html` | | | `404.php` | `templates/404.html` | | | `comments.php` | Block-based comments in template | `core/comments` block | | Custom page template | `templates/{{slug}}.html` + `customTemplates` entry in theme.json | Per template | | `woocommerce/` | WC block templates in `templates/` | See `references/woocommerce.md` |

Step 3: Convert functions.php

Identify which functionality must be kept vs replaced:

FUNCTIONS.PHP AUDIT
====================
KEEP (convert to FSE patterns):
  - Theme setup (add_theme_support calls)
  - Asset enqueueing (move to inc/enqueue.php)
  - Custom post type registration (move to inc/post-types.php)
  - Custom taxonomy registration (move to inc/taxonomies.php)
  - Block Bindings source registration (move to inc/block-bindings.php)

REPLACE (FSE handles this natively):
  - add_theme_support( 'menus' )         → core/navigation block
  - register_nav_menus()                 → core/navigation block
  - register_sidebar()                   → template parts
  - dynamic_sidebar()                    → template parts
  - wp_nav_menu()                        → core/navigation block
  - get_header() / get_footer()          → template parts referenced in templates
  - get_sidebar()                        → template parts

REMOVE (no longer needed in FSE):
  - add_theme_support( 'block-templates' )  → implicit in FSE
  - Custom walker_nav_menu classes          → core/navigation renders its own
  - Breadcrumb functions (if Yoast active)  → use breadcrumbs template part

Step 4: CSS Strategy

The classic theme's CSS cannot be used unchanged — it targets classic markup, not block markup.

Options:

**A. Full Rewrite (recommended for clean results)**

• Extract the design tokens (colors, fonts, spacing) → put in `theme.json`
• Rewrite CSS targeting block classes (`wp-block-*`) instead of classic selectors
• Use per-block CSS files in `assets/css/blocks/`

**B. Incremental Migration (for large CSS codebases)**

• Keep existing CSS as a global stylesheet
• Add per-block CSS overrides for block-specific elements
• Gradually refactor selectors over time

**C. CSS Audit + Cherry-Pick**

• Run Chrome DevTools Coverage tab → identify which CSS rules are actually used
• Copy used rules only, then rewrite selectors

Always state which approach is being taken and why.

Step 5: Convert Header and Footer

Convert `header.php` to `parts/header.html`:

**Classic `header.php` (simplified):**

<header class="site-header">
    <div class="container">
        <a href="<?php echo esc_url( home_url() ); ?>" class="site-logo">
            <?php bloginfo( 'name' ); ?>
        </a>
        <?php wp_nav_menu( array( 'theme_location' => 'primary' ) ); ?>
    </div>
</header>

**FSE `parts/header.html`:**

<!-- wp:group {"tagName":"header","className":"site-header","layout":{"type":"constrained"}} -->
<header class="wp-block-group site-header">
    <!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between","flexWrap":"nowrap"}} -->
    <div class="wp-block-group">
        <!-- wp:site-logo /-->
        <!-- wp:navigation {"ariaLabel":"<?php esc_attr_e( 'Primary', 'my-theme' ); ?>"} /-->
    </div>
    <!-- /wp:group -->
</header>
<!-- /wp:group -->

Step 6: Convert Templates

**Classic `single.php` (simplified):**

<?php get_header(); ?>