Building a Gutenberg-compatible WordPress theme from scratch01.04.26

building a Gutenberg-compatible WordPress theme from scratch involves understanding the core principles of block-based themes and how they interact with the WordPress block editor. Here's a step-by-step guide to get you started:

**1. Theme Setup (Basic Structure)**

*   **Create a Theme Directory:**  In your `wp-content/themes/` directory, create a new folder for your theme (e.g., `my-gutenberg-theme`).

*   **`style.css` (Required):**  Inside your theme directory, create a `style.css` file.  This is the only *required* file for a WordPress theme.

```css
    /*
    Theme Name:   My Gutenberg Theme
    Theme URI:    https://example.com/my-gutenberg-theme/
    Author:       Your Name
    Author URI:   https://example.com
    Description:  A basic Gutenberg-compatible theme.
    Version:      1.0.0
    License:      GNU General Public License v2 or later
    License URI:  http://www.gnu.org/licenses/gpl-2.0.html
    Text Domain:  my-gutenberg-theme
    */
    ```

*   **Important:**  Make sure to fill in the appropriate details.  The `Text Domain` is crucial for internationalization (i18n).

*   **`index.php` (Required):** Create an `index.php` file. This is the fallback template that WordPress will use if no other more specific template is found.

```php
    <!DOCTYPE html>
    <html <?php language_attributes(); ?>>
    <head>
        <meta charset="<?php bloginfo( 'charset' ); ?>">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link rel="profile" href="http://gmpg.org/xfn/11">
        <?php wp_head(); ?>
    </head>

<nav id="site-navigation" class="main-navigation">
                <button class="menu-toggle" aria-controls="primary-menu" aria-expanded="false"><?php esc_html_e( 'Primary Menu', 'my-gutenberg-theme' ); ?></button>
                <?php
                wp_nav_menu( array(
                    'theme_location' => 'menu-1',
                    'menu_id'        => 'primary-menu',
                ) );
                ?>
            </nav>
        </header>

<?php
                    if ( have_posts() ) :

if ( is_home() && ! is_front_page() ) :
                            ?>
                            <header>
                                <h1 class="page-title screen-reader-text"><?php single_post_title(); ?></h1>
                            </header>
                            <?php
                        endif;

/* Start the Loop */
                        while ( have_posts() ) :
                            the_post();

get_template_part( 'template-parts/content', get_post_type() );

endwhile;

the_posts_navigation();

else :

get_template_part( 'template-parts/content', 'none' );

endif;
                    ?>

</main>
            </div>
            <?php get_sidebar(); ?>
        </div>

<?php wp_footer(); ?>

</body>
    </html>
    ```

*   **`wp_head()` and `wp_footer()`:** These are *essential*.  They allow WordPress and plugins to inject necessary code (CSS, JavaScript) into your theme.
    *   **`language_attributes()`:**  Outputs the language attributes for the `<html>` tag (e.g., `lang="en-US"`).  Important for accessibility and SEO.
    *   **`body_class()`:** Adds helpful CSS classes to the `<body>` tag, allowing you to target specific pages or conditions with your CSS.
    *   **The Loop:** The `while ( have_posts() ) : the_post();` loop is the standard WordPress loop for displaying posts.  We're using `get_template_part()` to load the actual content from a separate template file (more on that later).
    *   **`get_sidebar()`:**  Loads the sidebar, if you have one.
    *   **Text Domain:**  Notice the use of `esc_html_e( 'Some text', 'my-gutenberg-theme' )`.  This is for internationalization.  The text domain should match the one you defined in `style.css`.

*   **Activate the Theme:**  Go to your WordPress admin panel (Appearance -> Themes) and activate your new theme.  You should now see a very basic, unstyled website.

**2. Gutenberg Compatibility**

*   **`functions.php`:** Create a `functions.php` file in your theme directory.  This is where you'll add code to enable Gutenberg features and customize your theme.

```php
    <?php

/**
     * My Gutenberg Theme functions and definitions.
     *
     * @link https://developer.wordpress.org/themes/basics/theme-functions/
     *
     * @package My_Gutenberg_Theme
     */

if ( ! function_exists( 'my_gutenberg_theme_setup' ) ) :
        /**
         * Sets up theme defaults and registers support for various WordPress features.
         *
         * Note that this function is hooked into the after_setup_theme hook, which
         * runs before the init hook. The init hook is too late for some features, such
         * as indicating support for post thumbnails.
         */
        function my_gutenberg_theme_setup() {
            /*
             * Make theme available for translation.
             * Translations can be filed in the /languages/ directory.
             * If you're building a theme based on My Gutenberg Theme, use a find and replace
             * to change 'my-gutenberg-theme' to the name of your theme in all the template files.
             */
            load_theme_textdomain( 'my-gutenberg-theme', get_template_directory() . '/languages' );

// Add default posts and comments RSS feed links to head.
            add_theme_support( 'automatic-feed-links' );

/*
             * Let WordPress manage the document title.
             * By adding theme support, we declare that this theme does not use a
             * hard-coded <title> tag in the document head, and expect WordPress to
             * provide it for us.
             */
            add_theme_support( 'title-tag' );

/*
             * Enable support for Post Thumbnails on posts and pages.
             *
             * @link https://developer.wordpress.org/themes/functionality/featured-images-post-thumbnails/
             */
            add_theme_support( 'post-thumbnails' );

// This theme uses wp_nav_menu() in one location.
            register_nav_menus( array(
                'menu-1' => esc_html__( 'Primary', 'my-gutenberg-theme' ),
            ) );

/*
             * Switch default core markup for search form, comment form, and comments
             * to output valid HTML5.
             */
            add_theme_support( 'html5', array(
                'search-form',
                'comment-form',
                'comment-list',
                'gallery',
                'caption',
            ) );

/*
             * Enable support for Post Formats.
             *
             * See: https://developer.wordpress.org/themes/functionality/post-formats/
             */
            add_theme_support( 'post-formats', array(
                'aside',
                'image',
                'video',
                'quote',
                'link',
            ) );

// Set up the WordPress core custom background feature.
            add_theme_support( 'custom-background', apply_filters( 'my_gutenberg_theme_custom_background_args', array(
                'default-color' => 'ffffff',
                'default-image' => '',
            ) ) );

// Add theme support for selective refresh for widgets.
            add_theme_support( 'customize-selective-refresh-widgets' );

/**
             * Add support for core custom logo.
             *
             * @link https://codex.wordpress.org/Theme_Logo
             */
            add_theme_support( 'custom-logo', array(
                'height'      => 250,
                'width'       => 250,
                'flex-width'  => true,
                'flex-height' => true,
            ) );

// Gutenberg Support
            add_theme_support( 'align-wide' ); // Enable wide and full alignment
            add_theme_support( 'wp-block-styles' ); //  Add default block styles
            add_theme_support( 'editor-styles' ); //  Add editor styles (see below)

// Add custom editor stylesheet
            add_editor_style( 'editor-style.css' );
        }
    endif; // My_Gutenberg_Theme_setup
    add_action( 'after_setup_theme', 'my_gutenberg_theme_setup' );

/**
     * Set the content width in pixels, based on the theme's design and stylesheet.
     *
     * Priority 0 to make it available to lower priority callbacks.
     *
     * @global int $content_width
     */
    function my_gutenberg_theme_content_width() {
        $GLOBALS['content_width'] = apply_filters( 'my_gutenberg_theme_content_width', 640 );
    }
    add_action( 'after_setup_theme', 'my_gutenberg_theme_content_width', 0 );

/**
     * Register widget area.
     *
     * @link https://developer.wordpress.org/themes/functionality/sidebars/#registering-a-sidebar
     */
    function my_gutenberg_theme_widgets_init() {
        register_sidebar( array(
            'name'          => esc_html__( 'Sidebar', 'my-gutenberg-theme' ),
            'id'            => 'sidebar-1',
            'description'   => esc_html__( 'Add widgets here.', 'my-gutenberg-theme' ),
            'before_widget' => '<section id="%1$s" class="widget %2$s">',
            'after_widget'  => '</section>',
            'before_title'  => '<h2 class="widget-title">',
            'after_title'   => '</h2>',
        ) );
    }
    add_action( 'widgets_init', 'my_gutenberg_theme_widgets_init' );

/**
     * Enqueue scripts and styles.
     */
    function my_gutenberg_theme_scripts() {
        wp_enqueue_style( 'my-gutenberg-theme-style', get_stylesheet_uri() );

wp_enqueue_script( 'my-gutenberg-theme-navigation', get_template_directory_uri() . '/js/navigation.js', array(), '20151215', true );

wp_enqueue_script( 'my-gutenberg-theme-skip-link-focus-fix', get_template_directory_uri() . '/js/skip-link-focus-fix.js', array(), '20151215', true );

if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
            wp_enqueue_script( 'comment-reply' );
        }
    }
    add_action( 'wp_enqueue_scripts', 'my_gutenberg_theme_scripts' );

/**
     * Implement the Custom Header feature.
     */
    require get_template_directory() . '/inc/custom-header.php';

/**
     * Custom template tags for this theme.
     */
    require get_template_directory() . '/inc/template-tags.php';

/**
     * Custom functions that act independently of the theme templates.
     */
    require get_template_directory() . '/inc/template-functions.php';

/**
     * Customizer additions.
     */
    require get_template_directory() . '/inc/customizer.php';

/**
     * Load Jetpack compatibility file.
     */
    require get_template_directory() . '/inc/jetpack.php';

```

*   **`add_theme_support( 'align-wide' )`:**  This is *critical*. It enables the "wide" and "full" alignment options for blocks in the Gutenberg editor.  Without this, blocks will be constrained to the content area width.
    *   **`add_theme_support( 'wp-block-styles' )`:**  This loads the default styles for core blocks.  It provides a basic level of styling so your blocks don't look completely unstyled.
    *   **`add_theme_support( 'editor-styles' )`:**  This tells WordPress to load a stylesheet in the Gutenberg editor, so the editor looks more like the front-end of your site.  We'll create `editor-style.css` in the next step.
    *   **`add_editor_style( 'editor-style.css' )`:**  Specifies the stylesheet to load in the editor.  This should be a relative path to your theme's directory.

*   **`editor-style.css`:** Create an `editor-style.css` file in your theme directory.  This is where you'll define styles that will be applied *only* in the Gutenberg editor.  This helps ensure that the editor looks similar to the front-end of your site.

```css
    /* Editor Styles */

body {
        font-family: sans-serif; /* Example: Set a basic font */
        font-size: 16px;
        line-height: 1.6;
    }

.wp-block {
        max-width: 740px; /* Example: Limit block width */
        margin-left: auto;
        margin-right: auto;
    }

.wp-block[data-align="wide"] {
        max-width: 1080px; /* Example: Wider width for wide blocks */
    }

.wp-block[data-align="full"] {
        max-width: none; /* Example: Full width blocks */
    }

/* Add more styles here to match your front-end */
    ```

*   **Important:**  The styles in `editor-style.css` should *mimic* the styles you'll use on the front-end.  This creates a WYSIWYG (What You See Is What You Get) experience in the editor.
    *   **`.wp-block`:**  This is the base class applied to all blocks in the editor.
    *   **`[data-align="wide"]` and `[data-align="full"]`:**  These are attribute selectors that target blocks with the "wide" and "full" alignment options.

**3. Basic Styling (Front-End)**

*   **`style.css` (Continued):**  Add basic styles to your `style.css` file to make your theme look presentable.  This is where you'll define the overall look and feel of your site.

body {
        font-family: sans-serif;
        font-size: 16px;
        line-height: 1.6;
        margin: 0;
        padding: 0;
    }

.site {
        max-width: 960px;
        margin: 0 auto;
        padding: 20px;
    }

.site-header {
        background-color: #f0f0f0;
        padding: 20px;
        margin-bottom: 20px;
    }

.site-title a {
        text-decoration: none;
        color: #333;
    }

.site-content {
        display: flex;
    }

#primary {
        width: 70%;
        margin-right: 20px;
    }

#secondary {
        width: 30%;
    }

.entry-content {
        margin-bottom: 20px;
    }

.entry-content p {
        margin-bottom: 1em;
    }

/* Add more styles here */
    ```

*   **Focus on Layout:**  Start by styling the basic layout elements (header, content, sidebar, footer).
    *   **Typography:**  Set a base font family, font size, and line height.
    *   **Spacing:**  Use margins and padding to create visual separation.

**4. Template Parts (Organization)**

*   **`template-parts` Directory:** Create a directory named `template-parts` in your theme directory.  This is a common practice for organizing reusable template snippets.

*   **`content.php` (or `content-page.php`, `content-post.php`):**  Create a file named `content.php` (or `content-page.php` for pages, `content-post.php` for posts) inside the `template-parts` directory.  This file will contain the HTML for displaying a single post or page.

```php
    <?php
    /**
     * Template part for displaying posts.
     *
     * @link https://codex.wordpress.org/Template_Hierarchy
     *
     * @package My_Gutenberg_Theme
     */

<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
        <header class="entry-header">
            <?php
            if ( is_singular() ) :
                the_title( '<h1 class="entry-title">', '</h1>' );
            else :
                the_title( '<h2 class="entry-title"><a href="' . esc_url( get_permalink() ) . '" rel="bookmark">', '</a></h2>' );
            endif;

if ( 'post' === get_post_type() ) :
                ?>
                <div class="entry-meta">
                    <?php my_gutenberg_theme_posted_on(); ?>
                </div>
                <?php
            endif;
            ?>
        </header>

<div class="entry-content">
            <?php
            the_content();

wp_link_pages( array(
                'before' => '<div class="page-links">' . esc_html__( 'Pages:', 'my-gutenberg-theme' ),
                'after'  => '</div>',
            ) );
            ?>
        </div>

<footer class="entry-footer">
            <?php my_gutenberg_theme_entry_footer(); ?>
        </footer>
    </article>
    ```

*   **`the_content()`:**  This is *the most important part*.  It's where the content of your post or page (including the Gutenberg blocks) is displayed.
    *   **`post_class()`:**  Adds helpful CSS classes to the `<article>` tag, allowing you to target specific posts with your CSS.

*   **`content-none.php`:** Create a file named `content-none.php` inside the `template-parts` directory.  This file will be displayed when there are no posts to show (e.g., on an empty archive page).

```php
    <?php
    /**
     * Template part for displaying a message that posts cannot be found.
     *
     * @link https://codex.wordpress.org/Template_Hierarchy
     *
     * @package My_Gutenberg_Theme
     */

<div class="page-content">
            <?php
            if ( is_home() && current_user_can( 'publish_posts' ) ) :

printf(
                    '<p>' . wp_kses(
                        /* translators: 1: link to WP admin new post page. */
                        __( 'Ready to publish your first post? <a href="%1$s">Get started here</a>.', 'my-gutenberg-theme' ),
                        array(
                            'a' => array(
                                'href' => array(),
                            ),
                        )
                    ) . '</p>',
                    esc_url( admin_url( 'post-new.php' ) )
                );

else :
                ?>

<p><?php esc_html_e( 'It seems we can’t find what you’re looking for. Perhaps searching can help.', 'my-gutenberg-theme' ); ?></p>
                <?php
                get_search_form();

endif;
            ?>
        </div>
    </section>
    ```

**5. Other Important Files (Optional but Recommended)**

*   **`header.php`:**  Contains the HTML for the `<head>` section and the opening `<body>` tag, as well as the site header.  You can move the header section from `index.php` into this file.

*   **`footer.php`:**  Contains the HTML for the site footer and the closing `</body>` and `</html>` tags.  You can move the footer section from `index.php` into this file.

*   **`sidebar.php`:**  Contains the HTML for the sidebar.

*   **`page.php`:**  Template file specifically for displaying pages.  If you don't have this, WordPress will use `index.php`.

*   **`single.php`:** Template file specifically for displaying single posts.  If you don't have this, WordPress will use `index.php`.

*   **`archive.php`:** Template file for displaying archive pages (e.g., category archives, tag archives).

*   **`search.php`:** Template file for displaying search results.

*   **`404.php`:** Template file for displaying the "404 Not Found" page.

**6. Customizer Support (Optional but Recommended)**

*   **`inc/customizer.php`:** Create a directory named `inc` and a file named `customizer.php` inside it.  This is where you'll add code to add custom settings to the WordPress Customizer (Appearance -> Customize).

```php
    <?php
    /**
     * My Gutenberg Theme Theme Customizer.
     *
     * @package My_Gutenberg_Theme
     */

/**
     * Add postMessage support for site title and description for the Theme Customizer.
     *
     * @param WP_Customize_Manager $wp_customize Theme Customizer object.
     */
    function my_gutenberg_theme_customize_register( $wp_customize ) {
        $wp_customize->get_setting( 'blogname' )->transport         = 'postMessage';
        $wp_customize->get_setting( 'blogdescription' )->transport  = 'postMessage';
        $wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';

if ( isset( $wp_customize->selective_refresh ) ) {
            $wp_customize->selective_refresh->add_partial( 'blogname', array(
                'selector'        => '.site-title a',
                'render_callback' => 'my_gutenberg_theme_customize_partial_blogname',
            ) );
            $wp_customize->selective_refresh->add_partial( 'blogdescription', array(
                'selector'        => '.site-description',
                'render_callback' => 'my_gutenberg_theme_customize_partial_blogdescription',
            ) );
        }
    }
    add_action( 'customize_register', 'my_gutenberg_theme_customize_register' );

/**
     * Render the site title for the selective refresh partial.
     *
     * @return void
     */
    function my_gutenberg_theme_customize_partial_blogname() {
        bloginfo( 'name' );
    }

/**
     * Render the site tagline for the selective refresh partial.
     *
     * @return void
     */
    function my_gutenberg_theme_customize_partial_blogdescription() {
        bloginfo( 'description' );
    }

/**
     * Binds JS handlers to make Theme Customizer preview reload changes asynchronously.
     */
    function my_gutenberg_theme_customize_preview_js() {
        wp_enqueue_script( 'my-gutenberg-theme-customizer', get_template_directory_uri() . '/js/customizer.js', array( 'customize-preview' ), '20151215', true );
    }
    add_action( 'customize_preview_init', 'my_gutenberg_theme_customize_preview_js' );
    ```

*   **Example:**  This code adds support for real-time updates of the site title and description in the Customizer.
    *   **`$wp_customize->add_setting()` and `$wp_customize->add_control()`:**  These are the core functions for adding custom settings and controls to the Customizer.

**7. JavaScript (Optional)**

*   **`js/navigation.js`:**  This file typically handles the functionality of the main navigation menu (e.g., toggling the menu on mobile devices).

*   **`js/skip-link-focus-fix.js`:**  This file improves accessibility by ensuring that the "skip to content" link works correctly in all browsers.

*   **`js/customizer.js`:**  This file handles the real-time updates in the Customizer (if you're using the Customizer).

**Key Considerations for Gutenberg Compatibility:**

*   **Content Width:**  Carefully consider the content width of your theme.  Gutenberg blocks will be displayed within this width by default.  Use the `align-wide` theme support to allow blocks to be wider.
*   **CSS Specificity:**  Be mindful of CSS specificity.  Gutenberg blocks have their own default styles, so you may need to use more specific CSS selectors to override them.
*   **Editor Styles:**  Keep your `editor-style.css` file up-to-date with your front-end styles.  This will ensure a consistent editing experience.
*   **Block Patterns:**  Consider creating custom block patterns to provide users with pre-designed layouts.
*   **Custom Blocks:**  If you need more control over the appearance and functionality of your blocks, you can create custom Gutenberg blocks.  This requires JavaScript and PHP development.
*   **Full Site Editing (Block Themes):**  Keep an eye on the evolution of Full Site Editing (FSE).  FSE allows you to use Gutenberg to edit *all* parts of your site, including the header, footer, and sidebars.  This is the future of WordPress theme development.  To create a block theme, you'll need to include a `theme.json` file.

**Example `theme.json` (for Full Site Editing):**

```json
{
	"version": 2,
	"settings": {
		"appearanceTools": true,
		"color": {
			"palette": [
				{
					"color": "#000000",
					"name": "Black"
				},
				{
					"color": "#ffffff",
					"name": "White"
				},
				{
					"color": "#f0f0f0",
					"name": "Light Gray"
				}
			],
			"gradients": [],
			"link": true
		},
		"layout": {
			"contentSize": "640px",
			"wideSize": "1080px"
		},
		"spacing": {
			"units": [ "px", "%", "em", "rem", "vw", "vh" ]
		},
		"typography": {
			"fontFamilies": [
				{
					"fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Oxygen-Sans, Ubuntu, Cantarell, \"Helvetica Neue\", sans-serif",
					"name": "System Font",
					"slug": "system-font"
				}
			],
			"fontSizes": [
				{
					"size": "16px",
					"slug": "normal",
					"name": "Normal"
				},
				{
					"size": "20px",
					"slug": "large",
					"name": "Large"
				}
			]
		}
	},
	"styles": {
		"elements": {
			"link": {
				"color": {
					"text": "#007bff"
				}
			}
		},
		"blocks": {
			"core/button": {
				"color": {
					"text": "#ffffff",
					"background": "#007bff"
				}
			}
		}
	}
}
```

*   **`theme.json`:** This file is the heart of a block theme. It defines the theme's settings, styles, and templates.  It allows you to control many aspects of the editor and the front-end without writing CSS.

**In Summary:**

1.  **Basic Theme Structure:** Create `style.css`, `index.php`, and `functions.php`.
2.  **Gutenberg Support:** Add `add_theme_support()` for `align-wide`, `wp-block-styles`, and `editor-styles` in `functions.php`.
3.  **Editor Styles:** Create `editor-style.css` to style the Gutenberg editor.
4.  **Template Parts:** Organize your theme using template parts (e.g., `content.php`).
5.  **Style the Front-End:** Style your theme using `style.css`.
6.  **Consider Full Site Editing:**  Explore `theme.json` for block themes.

This is a starting point.  Building a complete WordPress theme is a complex process, but this guide should give you a solid foundation for creating a Gutenberg-compatible theme from scratch. Remember to consult the WordPress Developer Handbook for more detailed information: [https://developer.wordpress.org/themes/](https://developer.wordpress.org/themes/)

https://www.plandigi.com/blog/building-a-wordpress-block-based-theme-a-complete-guide/

Anonymous

Building a Gutenberg-compatible WordPress theme from scratch01.04.26

Information Epoch 1794471575