WordPress Gutenberg Theme: Structure, Hierarchy and Custom Templates

There are technically two ways to build themes now. One is the old standard way, where you have PHP templates (that follow the traditional template hierarchy). The other is block based themes that use blocks for everything.

My recommendation is to stick with traditional for now. Full Site Editing, which is part of the block based theme work is still in its infancy and you can still use the Gutenberg editor with the old template method. I do this exclusively in my work.

What I typically do is include a blocks folder inside my theme that in turn has my package.json file. This is where I put all my Gutenberg specific theme stuff. So I’ll have a sub folder (in blocks/src/) for blocks, plugins, block-styles, etc. I’ll then add all the necessary JS to make all those blocks and plugins. Then, for templating, I use the standard .php template files (e.g. archive-post_type.php, single.php, etc.).

When registering a custom post type, you can specify a default “template” of blocks:

register_post_type('post_type_slug', array(
    // ...
    'show_in_rest' => true, // Make sure to include this so it loads the Gutenberg editor
    'template' => array(
        array('core/heading', array(
            'level' => 2)
        ),
        array('core/paragraph'),
    ),
));

You can also lock the templates if you want. See template_lock for your options.

I’ve written some other answers on SO for things like how to get and set custom post meta using Gutenberg, and general best practices I use when working with custom post types in Gutenberg. I’d suggesting checking those out as well.