Setting Up and Registering Static Homepage and Front Page Layouts for Premium Gutenberg-First Themes

In block themes, the `

// Check if the function exists and is hooked correctly
if ( has_action( 'after_setup_theme', 'my_theme_register_static_front_page' ) ) {
    echo "Static front page support is registered correctly.\n";
} else {
    echo "Static front page support is NOT registered correctly.\n";
}

if ( has_action( 'after_setup_theme', 'my_theme_register_blog_posts_index' ) ) {
    echo "Blog posts index support is registered correctly.\n";
} else {
    echo "Blog posts index support is NOT registered correctly.\n";
}

# Example check for block theme template files
ls -l your-theme-directory/templates/front-page.html
ls -l your-theme-directory/templates/home.html

# Example check for classic theme template files
ls -l your-theme-directory/front-page.php
ls -l your-theme-directory/home.php
ls -l your-theme-directory/index.php

<!-- wp:post-content {"layout":{"type":"constrained"}} -->
<div class="wp-block-post-content"></div>
<!-- /wp:post-content -->

<!-- wp:query -->
<div class="wp-block-query">
    <!-- wp:post-template -->
    <article>
        <!-- wp:post-title -->
        <h2></h2>
        <!-- /wp:post-title -->
        <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
    </article>
    <!-- /wp:post-template -->
    <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

# Using Query Monitor plugin:
# 1. Install and activate Query Monitor.
# 2. Visit your site's front page and blog page.
# 3. In the admin bar, click on the "Query Monitor" menu.
# 4. Navigate to the "Templates" tab.
# 5. Observe the "Current Template File" and "Template Hierarchy" sections to see which file WordPress is loading.

// Check if the function exists and is hooked correctly
if ( has_action( 'after_setup_theme', 'my_theme_register_static_front_page' ) ) {
    echo "Static front page support is registered correctly.\n";
} else {
    echo "Static front page support is NOT registered correctly.\n";
}

if ( has_action( 'after_setup_theme', 'my_theme_register_blog_posts_index' ) ) {
    echo "Blog posts index support is registered correctly.\n";
} else {
    echo "Blog posts index support is NOT registered correctly.\n";
}

# Example check for block theme template files
ls -l your-theme-directory/templates/front-page.html
ls -l your-theme-directory/templates/home.html

# Example check for classic theme template files
ls -l your-theme-directory/front-page.php
ls -l your-theme-directory/home.php
ls -l your-theme-directory/index.php

<!-- wp:post-content {"layout":{"type":"constrained"}} -->
<div class="wp-block-post-content"></div>
<!-- /wp:post-content -->

<!-- wp:query -->
<div class="wp-block-query">
    <!-- wp:post-template -->
    <article>
        <!-- wp:post-title -->
        <h2></h2>
        <!-- /wp:post-title -->
        <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
    </article>
    <!-- /wp:post-template -->
    <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

# Using Query Monitor plugin:
# 1. Install and activate Query Monitor.
# 2. Visit your site's front page and blog page.
# 3. In the admin bar, click on the "Query Monitor" menu.
# 4. Navigate to the "Templates" tab.
# 5. Observe the "Current Template File" and "Template Hierarchy" sections to see which file WordPress is loading.

<!-- wp:template-part {"slug":"header","theme":"your-theme-slug"} -->
<header></header>
<!-- /wp:template-part -->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main>
    <!-- wp:query -->
    <div class="wp-block-query">
        <!-- wp:post-template -->
        <article>
            <!-- wp:post-title -->
            <h2></h2>
            <!-- /wp:post-title -->
            <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
        </article>
        <!-- /wp:post-template -->
        <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
    </div>
    <!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","theme":"your-theme-slug"} -->
<footer></footer>
<!-- /wp:template-part -->

// Check if the function exists and is hooked correctly
if ( has_action( 'after_setup_theme', 'my_theme_register_static_front_page' ) ) {
    echo "Static front page support is registered correctly.\n";
} else {
    echo "Static front page support is NOT registered correctly.\n";
}

if ( has_action( 'after_setup_theme', 'my_theme_register_blog_posts_index' ) ) {
    echo "Blog posts index support is registered correctly.\n";
} else {
    echo "Blog posts index support is NOT registered correctly.\n";
}

# Example check for block theme template files
ls -l your-theme-directory/templates/front-page.html
ls -l your-theme-directory/templates/home.html

# Example check for classic theme template files
ls -l your-theme-directory/front-page.php
ls -l your-theme-directory/home.php
ls -l your-theme-directory/index.php

<!-- wp:post-content {"layout":{"type":"constrained"}} -->
<div class="wp-block-post-content"></div>
<!-- /wp:post-content -->

<!-- wp:query -->
<div class="wp-block-query">
    <!-- wp:post-template -->
    <article>
        <!-- wp:post-title -->
        <h2></h2>
        <!-- /wp:post-title -->
        <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
    </article>
    <!-- /wp:post-template -->
    <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

# Using Query Monitor plugin:
# 1. Install and activate Query Monitor.
# 2. Visit your site's front page and blog page.
# 3. In the admin bar, click on the "Query Monitor" menu.
# 4. Navigate to the "Templates" tab.
# 5. Observe the "Current Template File" and "Template Hierarchy" sections to see which file WordPress is loading.

/**
 * Register theme support for custom front page.
 */
function my_theme_register_static_front_page() {
    add_theme_support( 'custom-front-page' );
}
add_action( 'after_setup_theme', 'my_theme_register_static_front_page' );

/**
 * Register theme support for custom blog posts index.
 */
function my_theme_register_blog_posts_index() {
    add_theme_support( 'custom-blog-posts' );
}
add_action( 'after_setup_theme', 'my_theme_register_blog_posts_index' );

<!-- wp:template-part {"slug":"header","theme":"your-theme-slug"} -->
<header></header>
<!-- /wp:template-part -->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main>
    <!-- wp:post-content {"layout":{"type":"constrained"}} -->
    <div class="wp-block-post-content"></div>
    <!-- /wp:post-content -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","theme":"your-theme-slug"} -->
<footer></footer>
<!-- /wp:template-part -->

<!-- wp:template-part {"slug":"header","theme":"your-theme-slug"} -->
<header></header>
<!-- /wp:template-part -->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main>
    <!-- wp:query -->
    <div class="wp-block-query">
        <!-- wp:post-template -->
        <article>
            <!-- wp:post-title -->
            <h2></h2>
            <!-- /wp:post-title -->
            <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
        </article>
        <!-- /wp:post-template -->
        <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
    </div>
    <!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","theme":"your-theme-slug"} -->
<footer></footer>
<!-- /wp:template-part -->

// Check if the function exists and is hooked correctly
if ( has_action( 'after_setup_theme', 'my_theme_register_static_front_page' ) ) {
    echo "Static front page support is registered correctly.\n";
} else {
    echo "Static front page support is NOT registered correctly.\n";
}

if ( has_action( 'after_setup_theme', 'my_theme_register_blog_posts_index' ) ) {
    echo "Blog posts index support is registered correctly.\n";
} else {
    echo "Blog posts index support is NOT registered correctly.\n";
}

# Example check for block theme template files
ls -l your-theme-directory/templates/front-page.html
ls -l your-theme-directory/templates/home.html

# Example check for classic theme template files
ls -l your-theme-directory/front-page.php
ls -l your-theme-directory/home.php
ls -l your-theme-directory/index.php

<!-- wp:post-content {"layout":{"type":"constrained"}} -->
<div class="wp-block-post-content"></div>
<!-- /wp:post-content -->

<!-- wp:query -->
<div class="wp-block-query">
    <!-- wp:post-template -->
    <article>
        <!-- wp:post-title -->
        <h2></h2>
        <!-- /wp:post-title -->
        <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
    </article>
    <!-- /wp:post-template -->
    <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

# Using Query Monitor plugin:
# 1. Install and activate Query Monitor.
# 2. Visit your site's front page and blog page.
# 3. In the admin bar, click on the "Query Monitor" menu.
# 4. Navigate to the "Templates" tab.
# 5. Observe the "Current Template File" and "Template Hierarchy" sections to see which file WordPress is loading.

The `` block is essential here. It instructs WordPress to fetch and display posts according to the query set (by default, the latest posts). The `` defines how each individual post within the loop should be rendered. For classic themes, `index.php` or a dedicated `home.php` file would serve this purpose, using the standard WordPress Loop.

Classic Theme Fallbacks and Naming Conventions

If your theme is a classic theme or a hybrid theme that still relies on PHP files for templates, the naming conventions are critical:

• Front Page: `front-page.php` (highest priority) or `home.php` (if `front-page.php` doesn’t exist and ‘custom-front-page’ is supported).
• Blog Posts Index: `home.php` (if `front-page.php` is set to display latest posts) or `index.php` (as a fallback). If ‘custom-blog-posts’ is supported and a static page is assigned, WordPress will use the template assigned to that page. If no specific template is assigned to the static posts page, it will fall back to `home.php` or `index.php`.

It’s important to note that for classic themes, the `add_theme_support( ‘custom-front-page’ )` and `add_theme_support( ‘custom-blog-posts’ )` flags primarily enable the *options* in the WordPress admin. The actual rendering is still dictated by the template hierarchy and the presence of files like `front-page.php`, `home.php`, and `index.php`.

Advanced Diagnostics: Troubleshooting Template Rendering

When static front page or blog page layouts aren’t rendering as expected, several diagnostic steps can pinpoint the issue:

1. Verify Theme Support Registration

The most common oversight is missing or incorrectly placed `add_theme_support()` calls. Ensure they are within the `after_setup_theme` action hook in `functions.php`.

// Check if the function exists and is hooked correctly
if ( has_action( 'after_setup_theme', 'my_theme_register_static_front_page' ) ) {
    echo "Static front page support is registered correctly.\n";
} else {
    echo "Static front page support is NOT registered correctly.\n";
}

if ( has_action( 'after_setup_theme', 'my_theme_register_blog_posts_index' ) ) {
    echo "Blog posts index support is registered correctly.\n";
} else {
    echo "Blog posts index support is NOT registered correctly.\n";
}

You can temporarily add this diagnostic code to your `functions.php` (and remove it afterward) to confirm the actions are hooked. Alternatively, use a plugin like “Query Monitor” which lists all registered theme supports.

2. Check WordPress Admin Settings

Navigate to Settings > Reading in the WordPress admin. Verify that “Your homepage displays” is set to “A static page.” Ensure that both the “Homepage” and “Posts page” dropdowns have valid pages selected. If these options are not present, theme support is likely not registered.

3. Inspect Template File Names and Locations

For block themes, ensure the `templates/front-page.html` and `templates/home.html` files exist in your theme’s root directory. For classic themes, confirm the presence and correct naming of `front-page.php`, `home.php`, and `index.php` according to the template hierarchy.

# Example check for block theme template files
ls -l your-theme-directory/templates/front-page.html
ls -l your-theme-directory/templates/home.html

# Example check for classic theme template files
ls -l your-theme-directory/front-page.php
ls -l your-theme-directory/home.php
ls -l your-theme-directory/index.php

4. Examine Template File Content (Block Themes)

In block themes, the `` block within `front-page.html` is responsible for rendering the content of the assigned static front page. If this block is missing or malformed, the page content won’t appear. Similarly, the `` block in `home.html` is vital for displaying posts.

<!-- wp:post-content {"layout":{"type":"constrained"}} -->
<div class="wp-block-post-content"></div>
<!-- /wp:post-content -->

<!-- wp:query -->
<div class="wp-block-query">
    <!-- wp:post-template -->
    <article>
        <!-- wp:post-title -->
        <h2></h2>
        <!-- /wp:post-title -->
        <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
    </article>
    <!-- /wp:post-template -->
    <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

Use the Site Editor to inspect the structure of your `front-page.html` and `home.html` templates. Ensure these core blocks are present and correctly configured.

5. Check for Plugin Conflicts

A common cause of unexpected behavior is conflicts with other plugins. Temporarily deactivate all plugins except those essential for your theme’s functionality. If the issue resolves, reactivate plugins one by one to identify the culprit.

6. Template Hierarchy Debugging

For classic themes, understanding the WordPress template hierarchy is key. If `front-page.php` is present, it will be used for the front page. If not, WordPress falls back to `home.php`. For the blog index, `home.php` is used if the front page is set to static posts, otherwise `index.php`. The “Query Monitor” plugin is invaluable here, as it displays which template file is being loaded for the current page.

# Using Query Monitor plugin:
# 1. Install and activate Query Monitor.
# 2. Visit your site's front page and blog page.
# 3. In the admin bar, click on the "Query Monitor" menu.
# 4. Navigate to the "Templates" tab.
# 5. Observe the "Current Template File" and "Template Hierarchy" sections to see which file WordPress is loading.

By systematically applying these diagnostic steps, developers can effectively troubleshoot and ensure their Gutenberg-first themes correctly register and render static front page and blog posts index layouts, providing a seamless user experience.

The `` block is essential here. It instructs WordPress to fetch and display posts according to the query set (by default, the latest posts). The `` defines how each individual post within the loop should be rendered. For classic themes, `index.php` or a dedicated `home.php` file would serve this purpose, using the standard WordPress Loop.

Classic Theme Fallbacks and Naming Conventions

If your theme is a classic theme or a hybrid theme that still relies on PHP files for templates, the naming conventions are critical:

• Front Page: `front-page.php` (highest priority) or `home.php` (if `front-page.php` doesn’t exist and ‘custom-front-page’ is supported).
• Blog Posts Index: `home.php` (if `front-page.php` is set to display latest posts) or `index.php` (as a fallback). If ‘custom-blog-posts’ is supported and a static page is assigned, WordPress will use the template assigned to that page. If no specific template is assigned to the static posts page, it will fall back to `home.php` or `index.php`.

It’s important to note that for classic themes, the `add_theme_support( ‘custom-front-page’ )` and `add_theme_support( ‘custom-blog-posts’ )` flags primarily enable the *options* in the WordPress admin. The actual rendering is still dictated by the template hierarchy and the presence of files like `front-page.php`, `home.php`, and `index.php`.

Advanced Diagnostics: Troubleshooting Template Rendering

When static front page or blog page layouts aren’t rendering as expected, several diagnostic steps can pinpoint the issue:

1. Verify Theme Support Registration

The most common oversight is missing or incorrectly placed `add_theme_support()` calls. Ensure they are within the `after_setup_theme` action hook in `functions.php`.

// Check if the function exists and is hooked correctly
if ( has_action( 'after_setup_theme', 'my_theme_register_static_front_page' ) ) {
    echo "Static front page support is registered correctly.\n";
} else {
    echo "Static front page support is NOT registered correctly.\n";
}

if ( has_action( 'after_setup_theme', 'my_theme_register_blog_posts_index' ) ) {
    echo "Blog posts index support is registered correctly.\n";
} else {
    echo "Blog posts index support is NOT registered correctly.\n";
}

You can temporarily add this diagnostic code to your `functions.php` (and remove it afterward) to confirm the actions are hooked. Alternatively, use a plugin like “Query Monitor” which lists all registered theme supports.

2. Check WordPress Admin Settings

Navigate to Settings > Reading in the WordPress admin. Verify that “Your homepage displays” is set to “A static page.” Ensure that both the “Homepage” and “Posts page” dropdowns have valid pages selected. If these options are not present, theme support is likely not registered.

3. Inspect Template File Names and Locations

For block themes, ensure the `templates/front-page.html` and `templates/home.html` files exist in your theme’s root directory. For classic themes, confirm the presence and correct naming of `front-page.php`, `home.php`, and `index.php` according to the template hierarchy.

# Example check for block theme template files
ls -l your-theme-directory/templates/front-page.html
ls -l your-theme-directory/templates/home.html

# Example check for classic theme template files
ls -l your-theme-directory/front-page.php
ls -l your-theme-directory/home.php
ls -l your-theme-directory/index.php

4. Examine Template File Content (Block Themes)

In block themes, the `` block within `front-page.html` is responsible for rendering the content of the assigned static front page. If this block is missing or malformed, the page content won’t appear. Similarly, the `` block in `home.html` is vital for displaying posts.

<!-- wp:post-content {"layout":{"type":"constrained"}} -->
<div class="wp-block-post-content"></div>
<!-- /wp:post-content -->

<!-- wp:query -->
<div class="wp-block-query">
    <!-- wp:post-template -->
    <article>
        <!-- wp:post-title -->
        <h2></h2>
        <!-- /wp:post-title -->
        <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
    </article>
    <!-- /wp:post-template -->
    <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

Use the Site Editor to inspect the structure of your `front-page.html` and `home.html` templates. Ensure these core blocks are present and correctly configured.

5. Check for Plugin Conflicts

A common cause of unexpected behavior is conflicts with other plugins. Temporarily deactivate all plugins except those essential for your theme’s functionality. If the issue resolves, reactivate plugins one by one to identify the culprit.

6. Template Hierarchy Debugging

For classic themes, understanding the WordPress template hierarchy is key. If `front-page.php` is present, it will be used for the front page. If not, WordPress falls back to `home.php`. For the blog index, `home.php` is used if the front page is set to static posts, otherwise `index.php`. The “Query Monitor” plugin is invaluable here, as it displays which template file is being loaded for the current page.

# Using Query Monitor plugin:
# 1. Install and activate Query Monitor.
# 2. Visit your site's front page and blog page.
# 3. In the admin bar, click on the "Query Monitor" menu.
# 4. Navigate to the "Templates" tab.
# 5. Observe the "Current Template File" and "Template Hierarchy" sections to see which file WordPress is loading.

By systematically applying these diagnostic steps, developers can effectively troubleshoot and ensure their Gutenberg-first themes correctly register and render static front page and blog posts index layouts, providing a seamless user experience.

This is a simplified example of a block theme’s `front-page.html`. The `` block is crucial as it dynamically renders the content of the page assigned as the static front page. For classic themes, `front-page.php` would contain PHP and potentially template tags to output content.

Blog Posts Index Template (`home.html` or `index.php`)

For the blog posts index, the convention differs slightly between block themes and classic themes. In block themes, `templates/home.html` is recognized as the template for the posts index when ‘custom-blog-posts’ support is enabled and a static page is assigned to the posts page.

<!-- wp:template-part {"slug":"header","theme":"your-theme-slug"} -->
<header></header>
<!-- /wp:template-part -->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main>
    <!-- wp:query -->
    <div class="wp-block-query">
        <!-- wp:post-template -->
        <article>
            <!-- wp:post-title -->
            <h2></h2>
            <!-- /wp:post-title -->
            <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
        </article>
        <!-- /wp:post-template -->
        <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
    </div>
    <!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","theme":"your-theme-slug"} -->
<footer></footer>
<!-- /wp:template-part -->

The `` block is essential here. It instructs WordPress to fetch and display posts according to the query set (by default, the latest posts). The `` defines how each individual post within the loop should be rendered. For classic themes, `index.php` or a dedicated `home.php` file would serve this purpose, using the standard WordPress Loop.

Classic Theme Fallbacks and Naming Conventions

If your theme is a classic theme or a hybrid theme that still relies on PHP files for templates, the naming conventions are critical:

• Front Page: `front-page.php` (highest priority) or `home.php` (if `front-page.php` doesn’t exist and ‘custom-front-page’ is supported).
• Blog Posts Index: `home.php` (if `front-page.php` is set to display latest posts) or `index.php` (as a fallback). If ‘custom-blog-posts’ is supported and a static page is assigned, WordPress will use the template assigned to that page. If no specific template is assigned to the static posts page, it will fall back to `home.php` or `index.php`.

It’s important to note that for classic themes, the `add_theme_support( ‘custom-front-page’ )` and `add_theme_support( ‘custom-blog-posts’ )` flags primarily enable the *options* in the WordPress admin. The actual rendering is still dictated by the template hierarchy and the presence of files like `front-page.php`, `home.php`, and `index.php`.

Advanced Diagnostics: Troubleshooting Template Rendering

When static front page or blog page layouts aren’t rendering as expected, several diagnostic steps can pinpoint the issue:

1. Verify Theme Support Registration

The most common oversight is missing or incorrectly placed `add_theme_support()` calls. Ensure they are within the `after_setup_theme` action hook in `functions.php`.

// Check if the function exists and is hooked correctly
if ( has_action( 'after_setup_theme', 'my_theme_register_static_front_page' ) ) {
    echo "Static front page support is registered correctly.\n";
} else {
    echo "Static front page support is NOT registered correctly.\n";
}

if ( has_action( 'after_setup_theme', 'my_theme_register_blog_posts_index' ) ) {
    echo "Blog posts index support is registered correctly.\n";
} else {
    echo "Blog posts index support is NOT registered correctly.\n";
}

You can temporarily add this diagnostic code to your `functions.php` (and remove it afterward) to confirm the actions are hooked. Alternatively, use a plugin like “Query Monitor” which lists all registered theme supports.

2. Check WordPress Admin Settings

Navigate to Settings > Reading in the WordPress admin. Verify that “Your homepage displays” is set to “A static page.” Ensure that both the “Homepage” and “Posts page” dropdowns have valid pages selected. If these options are not present, theme support is likely not registered.

3. Inspect Template File Names and Locations

For block themes, ensure the `templates/front-page.html` and `templates/home.html` files exist in your theme’s root directory. For classic themes, confirm the presence and correct naming of `front-page.php`, `home.php`, and `index.php` according to the template hierarchy.

# Example check for block theme template files
ls -l your-theme-directory/templates/front-page.html
ls -l your-theme-directory/templates/home.html

# Example check for classic theme template files
ls -l your-theme-directory/front-page.php
ls -l your-theme-directory/home.php
ls -l your-theme-directory/index.php

4. Examine Template File Content (Block Themes)

In block themes, the `` block within `front-page.html` is responsible for rendering the content of the assigned static front page. If this block is missing or malformed, the page content won’t appear. Similarly, the `` block in `home.html` is vital for displaying posts.

<!-- wp:post-content {"layout":{"type":"constrained"}} -->
<div class="wp-block-post-content"></div>
<!-- /wp:post-content -->

<!-- wp:query -->
<div class="wp-block-query">
    <!-- wp:post-template -->
    <article>
        <!-- wp:post-title -->
        <h2></h2>
        <!-- /wp:post-title -->
        <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
    </article>
    <!-- /wp:post-template -->
    <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

Use the Site Editor to inspect the structure of your `front-page.html` and `home.html` templates. Ensure these core blocks are present and correctly configured.

5. Check for Plugin Conflicts

A common cause of unexpected behavior is conflicts with other plugins. Temporarily deactivate all plugins except those essential for your theme’s functionality. If the issue resolves, reactivate plugins one by one to identify the culprit.

6. Template Hierarchy Debugging

For classic themes, understanding the WordPress template hierarchy is key. If `front-page.php` is present, it will be used for the front page. If not, WordPress falls back to `home.php`. For the blog index, `home.php` is used if the front page is set to static posts, otherwise `index.php`. The “Query Monitor” plugin is invaluable here, as it displays which template file is being loaded for the current page.

# Using Query Monitor plugin:
# 1. Install and activate Query Monitor.
# 2. Visit your site's front page and blog page.
# 3. In the admin bar, click on the "Query Monitor" menu.
# 4. Navigate to the "Templates" tab.
# 5. Observe the "Current Template File" and "Template Hierarchy" sections to see which file WordPress is loading.

By systematically applying these diagnostic steps, developers can effectively troubleshoot and ensure their Gutenberg-first themes correctly register and render static front page and blog posts index layouts, providing a seamless user experience.

Registering Static Front Page and Blog Page Templates

For premium Gutenberg-first themes, providing distinct, customizable layouts for the static front page and the blog posts index is crucial. This goes beyond simple page templates; it involves registering these specific template types with WordPress core to ensure they are correctly identified and selectable in the Site Editor or the Customizer’s “Homepage Settings.” This section details the PHP code required to achieve this registration, ensuring your theme adheres to modern WordPress standards.

The primary mechanism for this registration is the `add_theme_support()` function, specifically targeting the ‘custom_front_page’ and ‘custom_blog_posts’ features. These flags signal to WordPress that your theme intends to manage these specific page types via its template hierarchy.

Implementing the Registration in `functions.php`

The most robust place to implement this theme support is within your theme’s `functions.php` file. This ensures the registration happens early in the WordPress loading process.

Registering the Static Front Page Template Support

To enable the selection of a static front page, you need to add support for ‘custom_front_page’. This allows users to choose a specific page to serve as their homepage, rather than relying on the latest posts. When this support is active, WordPress will look for a page with the template assigned to the front page.

/**
 * Register theme support for custom front page.
 */
function my_theme_register_static_front_page() {
    add_theme_support( 'custom-front-page' );
}
add_action( 'after_setup_theme', 'my_theme_register_static_front_page' );

This code snippet hooks into the ‘after_setup_theme’ action, which is the recommended hook for adding theme supports. The `my_theme_register_static_front_page` function simply calls `add_theme_support( ‘custom-front-page’ )`.

Registering the Blog Posts Index Template Support

Similarly, to allow users to designate a static page as their blog posts index (where all their posts are displayed), you need to add support for ‘custom_blog_posts’. This is distinct from the front page; it’s specifically for the archive page of your posts.

/**
 * Register theme support for custom blog posts index.
 */
function my_theme_register_blog_posts_index() {
    add_theme_support( 'custom-blog-posts' );
}
add_action( 'after_setup_theme', 'my_theme_register_blog_posts_index' );

This function, `my_theme_register_blog_posts_index`, also hooks into ‘after_setup_theme’ and calls `add_theme_support( ‘custom-blog-posts’ )`. When both supports are active, the WordPress admin interface (under Settings > Reading) will present options to select a static page for the front page and another static page for the posts page.

Creating the Actual Page Templates

Registering the support is only half the battle. WordPress needs actual template files to render these static pages. For a Gutenberg-first theme, these templates will primarily be block-based, but they still require specific file naming conventions and headers to be recognized by WordPress.

Front Page Template (`front-page.html`)

For block themes, the front page template is typically handled by `templates/front-page.html`. For classic themes or hybrid themes that still use PHP templates for this purpose, you would create a file named `front-page.php` in your theme’s root directory. If you are using block templates, WordPress automatically recognizes `templates/front-page.html` as the default template for the front page when ‘custom-front-page’ support is enabled and a static front page is set.

<!-- wp:template-part {"slug":"header","theme":"your-theme-slug"} -->
<header></header>
<!-- /wp:template-part -->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main>
    <!-- wp:post-content {"layout":{"type":"constrained"}} -->
    <div class="wp-block-post-content"></div>
    <!-- /wp:post-content -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","theme":"your-theme-slug"} -->
<footer></footer>
<!-- /wp:template-part -->

This is a simplified example of a block theme’s `front-page.html`. The `` block is crucial as it dynamically renders the content of the page assigned as the static front page. For classic themes, `front-page.php` would contain PHP and potentially template tags to output content.

Blog Posts Index Template (`home.html` or `index.php`)

For the blog posts index, the convention differs slightly between block themes and classic themes. In block themes, `templates/home.html` is recognized as the template for the posts index when ‘custom-blog-posts’ support is enabled and a static page is assigned to the posts page.

<!-- wp:template-part {"slug":"header","theme":"your-theme-slug"} -->
<header></header>
<!-- /wp:template-part -->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main>
    <!-- wp:query -->
    <div class="wp-block-query">
        <!-- wp:post-template -->
        <article>
            <!-- wp:post-title -->
            <h2></h2>
            <!-- /wp:post-title -->
            <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
        </article>
        <!-- /wp:post-template -->
        <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
    </div>
    <!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","theme":"your-theme-slug"} -->
<footer></footer>
<!-- /wp:template-part -->

The `` block is essential here. It instructs WordPress to fetch and display posts according to the query set (by default, the latest posts). The `` defines how each individual post within the loop should be rendered. For classic themes, `index.php` or a dedicated `home.php` file would serve this purpose, using the standard WordPress Loop.

Classic Theme Fallbacks and Naming Conventions

If your theme is a classic theme or a hybrid theme that still relies on PHP files for templates, the naming conventions are critical:

• Front Page: `front-page.php` (highest priority) or `home.php` (if `front-page.php` doesn’t exist and ‘custom-front-page’ is supported).
• Blog Posts Index: `home.php` (if `front-page.php` is set to display latest posts) or `index.php` (as a fallback). If ‘custom-blog-posts’ is supported and a static page is assigned, WordPress will use the template assigned to that page. If no specific template is assigned to the static posts page, it will fall back to `home.php` or `index.php`.

It’s important to note that for classic themes, the `add_theme_support( ‘custom-front-page’ )` and `add_theme_support( ‘custom-blog-posts’ )` flags primarily enable the *options* in the WordPress admin. The actual rendering is still dictated by the template hierarchy and the presence of files like `front-page.php`, `home.php`, and `index.php`.

Advanced Diagnostics: Troubleshooting Template Rendering

When static front page or blog page layouts aren’t rendering as expected, several diagnostic steps can pinpoint the issue:

1. Verify Theme Support Registration

The most common oversight is missing or incorrectly placed `add_theme_support()` calls. Ensure they are within the `after_setup_theme` action hook in `functions.php`.

// Check if the function exists and is hooked correctly
if ( has_action( 'after_setup_theme', 'my_theme_register_static_front_page' ) ) {
    echo "Static front page support is registered correctly.\n";
} else {
    echo "Static front page support is NOT registered correctly.\n";
}

if ( has_action( 'after_setup_theme', 'my_theme_register_blog_posts_index' ) ) {
    echo "Blog posts index support is registered correctly.\n";
} else {
    echo "Blog posts index support is NOT registered correctly.\n";
}

You can temporarily add this diagnostic code to your `functions.php` (and remove it afterward) to confirm the actions are hooked. Alternatively, use a plugin like “Query Monitor” which lists all registered theme supports.

2. Check WordPress Admin Settings

Navigate to Settings > Reading in the WordPress admin. Verify that “Your homepage displays” is set to “A static page.” Ensure that both the “Homepage” and “Posts page” dropdowns have valid pages selected. If these options are not present, theme support is likely not registered.

3. Inspect Template File Names and Locations

For block themes, ensure the `templates/front-page.html` and `templates/home.html` files exist in your theme’s root directory. For classic themes, confirm the presence and correct naming of `front-page.php`, `home.php`, and `index.php` according to the template hierarchy.

# Example check for block theme template files
ls -l your-theme-directory/templates/front-page.html
ls -l your-theme-directory/templates/home.html

# Example check for classic theme template files
ls -l your-theme-directory/front-page.php
ls -l your-theme-directory/home.php
ls -l your-theme-directory/index.php

4. Examine Template File Content (Block Themes)

In block themes, the `` block within `front-page.html` is responsible for rendering the content of the assigned static front page. If this block is missing or malformed, the page content won’t appear. Similarly, the `` block in `home.html` is vital for displaying posts.

<!-- wp:post-content {"layout":{"type":"constrained"}} -->
<div class="wp-block-post-content"></div>
<!-- /wp:post-content -->

<!-- wp:query -->
<div class="wp-block-query">
    <!-- wp:post-template -->
    <article>
        <!-- wp:post-title -->
        <h2></h2>
        <!-- /wp:post-title -->
        <!-- wp:post-excerpt --></div><!-- /wp:post-excerpt -->
    </article>
    <!-- /wp:post-template -->
    <!-- wp:query-pagination --></div><!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

Use the Site Editor to inspect the structure of your `front-page.html` and `home.html` templates. Ensure these core blocks are present and correctly configured.

5. Check for Plugin Conflicts

A common cause of unexpected behavior is conflicts with other plugins. Temporarily deactivate all plugins except those essential for your theme’s functionality. If the issue resolves, reactivate plugins one by one to identify the culprit.

6. Template Hierarchy Debugging

For classic themes, understanding the WordPress template hierarchy is key. If `front-page.php` is present, it will be used for the front page. If not, WordPress falls back to `home.php`. For the blog index, `home.php` is used if the front page is set to static posts, otherwise `index.php`. The “Query Monitor” plugin is invaluable here, as it displays which template file is being loaded for the current page.

# Using Query Monitor plugin:
# 1. Install and activate Query Monitor.
# 2. Visit your site's front page and blog page.
# 3. In the admin bar, click on the "Query Monitor" menu.
# 4. Navigate to the "Templates" tab.
# 5. Observe the "Current Template File" and "Template Hierarchy" sections to see which file WordPress is loading.

By systematically applying these diagnostic steps, developers can effectively troubleshoot and ensure their Gutenberg-first themes correctly register and render static front page and blog posts index layouts, providing a seamless user experience.