Making Full Site Editing Block Theme for WordPress

In 2023 we have an option to finally work with full-site editing mode and to create a unique block theme inside WordPress’s new (Beta) Editor. I’ve started to make a new block theme for a multilanguage RTL website and write down my notes below.

Starting with a New Block Theme for Full Site Editing (FSE)

Block theme is somehow simpler to create. One can just duplicate the default WordPress 2023 theme and change the name to your new theme, as you wish + change to your new theme name through the theme files. There is also a plugin that helps with this process called “Create Block Theme“. It allows automatic cloning of the active block theme (i.e. 2023 theme) with a new name. And you can embed new local fonts with this plugin too.

Caveats

Most of your settings now will reside in your theme.json file. In fact, the 2023 theme doesn’t have any functioning PHP files at all. So be prepared to edit this JSON file a lot. And you can’t put any comments into JSON + no random commas at the end of expressions are allowed. Or everything will fail.

New Editor

Important to know, that default theme template files will be saved into the database once you modify and save them in the editor. So i.e. after everything was set up and ready, we can write it down back to the theme files with the help of the “Create Block Theme” plugin again (needs to be tested yet).

Local Fonts

After you add some local fonts to your theme, they may not display correctly, because the code will look for local fonts on your computer/browser first. To avoid this rename your local font of the theme to some unique name to push the browser to use your uploaded font.

 "typography": {
            "dropCap": false,
            "fluid": true,
            "customFontSize": true,
            "fontFamilies": [{
                "fontFamily": "\"UniqueName Heebo\", sans-serif",
                "slug": "heebo",
                "name": "Heebo",
                "fontFace": [{
                        "fontFamily": "UniqueName Heebo",
                        "fontWeight": "300",
                        "fontStyle": "normal",
                        "fontDisplay": "swap",
                        "src": ["file:./assets/fonts/heebo_300.woff2"]
                    },
                    {
                        "fontFamily": "UniqueName Heebo",
                        "fontWeight": "400",
                        "fontStyle": "normal",
                        "fontDisplay": "swap",
                        "src": ["file:./assets/fonts/heebo_regular.woff2"]
                    }
                ]
            }],

Editor Default Headings Font Not Loading in RTL Mode

Because of a piece of the default RTL editor’s style by WordPress 6.2 Headings are not getting the default font family style. Can be fixed by adding it through editor-style.css which can be loaded into the theme from functions.php

if ( ! function_exists( 'iggy_theme_support' ) ) :
	function iggy_theme_support() {
		// Enqueue editor styles.
		add_editor_style( 'css/editor-style.css' );
    }
endif;
add_action( 'after_setup_theme', 'iggy_theme_support' );

And then in editor-style.css

/* Editor */
h1, h2, h3, h4, h5, h6 {
    font-family: inherit;
}

But better to resolve it from the theme.json in the styles/elements section to overwrite default RTL styles for Headings:

"h1": {
       "typography": {
          "fontFamily": "var(--wp--preset--font-family--heebo)",
          "fontSize": "3.625rem",
          "lineHeight": "1.2"
          }
       },
"h2": {
       "typography": {
          "fontFamily": "var(--wp--preset--font-family--heebo)",
          "fontSize": "clamp(2.625rem, calc(2.625rem + ((1vw - 0.48rem) * 8.4135)), 3.25rem)",
          "lineHeight": "1.2"
          }
        },
"h3": {
       "typography": {
          "fontFamily": "var(--wp--preset--font-family--heebo)",
          "fontSize": "var(--wp--preset--font-size--x-large)"
          }
        },
"h4": {
       "typography": {
          "fontFamily": "var(--wp--preset--font-family--heebo)",
          "fontSize": "var(--wp--preset--font-size--large)"
          }
        },
"h5": {
       "typography": {
          "fontFamily": "var(--wp--preset--font-family--heebo)",
          "fontSize": "var(--wp--preset--font-size--medium)",
          "fontWeight": "700",
          "textTransform": "uppercase"
          }
        },
"h6": {
       "typography": {
          "fontFamily": "var(--wp--preset--font-family--heebo)",
          "fontSize": "var(--wp--preset--font-size--medium)",
          "textTransform": "uppercase"
          }
       },

Notice added "fontFamily" value.

Functions.php and CSS files for a block theme

I’ve found it impossible to make my unique theme without CSS files and functions.php additions. But these files are really small compared with a regular wp theme.

Calling CSS Files with Version Timestamp to Avoid Caches

if ( ! function_exists( 'iggy_styles' ) ) :
	function iggy_styles() {

		// Register theme stylesheet.
		wp_register_style( 'iggy-style', get_stylesheet_uri(), array(), filemtime( get_stylesheet_directory() . '/style.css' ) );

		// Enqueue theme stylesheet.
		wp_enqueue_style( 'iggy-style' );
	}

endif;
add_action( 'wp_enqueue_scripts', 'iggy_styles' );

// add version to rtl.css
add_filter( 'locale_stylesheet_uri', function ($localized_stylesheet_uri) {
    $time_ver = filemtime( get_stylesheet_directory() . '/rtl.css' );
    return add_query_arg( array('ver' => $time_ver), $localized_stylesheet_uri );
});

I’ve found it better not to replace the regular stylesheet with the RTL stylesheet, but to add additional RTL styles after the main style.css

Change Viewport Default Meta Tag and Add Color Theme for Mobile Browsers

I like my sites to cover the whole area on the iPhone screen in Landscape mode. So have to replace the viewport meta tag.

add_action('wp_head', function() {
	remove_action('wp_head', '_block_template_viewport_meta_tag', 0);
    echo '<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, viewport-fit=cover">';
    echo '<meta name="theme-color" content="#050E2A">';
}, PHP_INT_MIN);

WPML Compatibility

Header and Footer Editing

At the time of writing (version 4.5.14 of WPML Multilingual CMS plugin) WPML wasn’t compatible with FSE mode. You can’t translate the header and footer directly in the new FSE editor. Translating the header and footer in another language from the editor won’t have any effect yet.

Create a header and footer in your default language, resave the template into the database, and go to WPML → Translation Management. Then WPML recommends choosing the Template or Template Parts post type from the dropdown menu and selecting the templates. In the WPML new editor, it translated only texts without an option to translate links.

I’ve had better results when switched to WPML Classic Edfitor and allowed templates and template parts to be translated in WPML Settings. Then gone to Translation Management, sent the needed translations, like Menus, Header, and Footer to the Translations Queue, and translated the whole header block, footer + all menus. Beware, the editor opens in visual mode, switch to text to see the HTML, copy, and finish the translation job. Also “translate” Image IDs for the logo etc, if they’re different for different languages.

You also should create menus in additional language versions to be able to translate them via Strings Translation or better from the Translations Queue. Beware that not finished translation jobs from the Queue won’t show in the menus, even while fully translated via the String Translation.

Update 13/11/23

I can now edit menus directly in the Editor navigation editing even per language. That’s great! Other parts of template parts are still only editable per the default language and will need a translation through WPML.

Images in Template Parts

Images can be translated from Media Translation under the WPML menu. This is useful if not using some SVG code or image ID. Just upload another image as a translation. It’s replacing the untranslated image and also updating image size and ALT text.

Language Switcher

For now, there is no dedicated language switcher block available, so you have to use a shortcode block to install a language switcher as a shortcode. I.e.:

[wpml_language_switcher flags=0 native=1 translated=0][/wpml_language_switcher]

Update 28/5/23

WPML already has a language switcher block for FSE with many options. But it needs a translation, as other header/footer parts, just duplicate the default language code. Cheers!

Woocommerce Compatibility

Woocommerce already has some blocks available, so there are no problems discovered by me yet.