Block Theme Anatomy: A Simplified Explanation of Structure & Files
So you’ve decided to venture into the world of block themes but aren’t sure where to start? Don’t worry, we’ve got you covered. In this guide, we will provide you with an overview of a block theme’s file structure, commonly referred to as the “anatomy”. We’ll explain what folders and files can be found in a block theme, which ones are required, and what they all do. Whether you’re an experienced WordPress developer transitioning from classic themes or new to theme development altogether, this article will give you the information you need to get started.
To begin, we recommend downloading the twenty twenty four theme. This will serve as a reference point that you can modify to create your own unique block theme.
Block Theme Structure
At its core, a basic block theme consists of a folder containing a style.css file and a templates/index.html file. This provides the foundation for your theme. However, a more robust theme may have additional files and folders, as shown in the screenshot below from our Mesa WPEX theme.
Required Folders
When creating a block theme, there are a few folders that are required to be present:
1. templates: This folder contains the main template files for your theme. It is essential to have an index.html file inside this folder.
Optional Folders
While you can technically add any folder to your block theme, WordPress recognizes specific folders for certain purposes. These optional folders can enhance the functionality of your theme:
1. parts: Use this folder to store global template parts that can be used within other templates.
2. patterns: Place your custom patterns in this folder. Patterns are re-usable template areas that can be modified globally in the site editor.
3. styles: Store your custom styles (skins) in this folder. Each style is defined in a JSON file.
Required Files
The following files are necessary for a block theme to appear in the WordPress admin and function properly:
1. style.css: This file contains your theme’s “header” and provides information to WordPress about your theme, such as its name, description, version, etc. Refer to the official style.css documentation for proper setup.
2. templates/index.html: This is the main file used for the display of any archive, post, or page if no alternative template exists.
Required Files for the WordPress.org Repository
If you plan to upload your block theme to the WordPress repository, you must include the following files:
1. readme.txt: This file provides important information about your theme, including the description, installation instructions, credits, licenses, copyright, changelog, and more.
2. screenshot.png: This file is used for the theme’s screenshot in the WordPress admin under Appearance > Themes. Even if you’re not submitting your theme to the WordPress.org repository, including this file adds visual appeal.
Optional Files
While any file or folder can be added to your block theme, there are specific files that can serve various purposes:
1. rtl.css: This file is used for right-to-left language direction. However, modern CSS properties can handle direction-aware styling, making this file unnecessary in most cases.
2. theme.json: This file defines global settings and styles for your block theme. While optional, you will likely create one for each block theme you develop.
3. functions.php: This file is always loaded and can contain PHP code to enhance your block theme. You can also use it to include other PHP files.
Block Theme Template Files List
When creating your block theme, you’ll want to customize the display of different parts of your site. The following template files, when added to your block theme’s templates folder, allow you to modify specific sections:
1. home.html: Used for the “home” page, which displays your latest posts.
2. singular.html: Used for viewing single posts, both standard and custom. This file serves as a fallback for the single.html or single-{post_type} files.
3. single.html: Used for the display of a single post.
4. single-{post_type}.html: Used when viewing a specific custom post type post.
5. archive-{post_type}.html: Used for viewing a post type archive.
6. page.html: Used when viewing a standard page.
7. category.html: Used when viewing a singular category archive.
8. tag.html: Used when viewing a singular tag archive.
9. author.html: Used when viewing an author’s archive.
10. date.html: Used for date-based archives, such as site.com/2024/.
11. archive.html: Used for displaying a category, tag, or date archive if more specific templates don’t exist.
12. search.html: Used for the search results page.
13. attachment.html: Used when viewing a single attachment, such as an image or video.
14. image.html: This file overrides the attachment.html file and is used for displaying a single image page.
15. 404.html: Used when displaying a 404 error page.
Block Themes are Simple!
As you can see, creating a block theme requires only a few essential files, with optional files and folders providing enhanced functionality. The structure of a block theme is straightforward and easy to understand. Hopefully, this guide has helped clarify any confusion and provided you with the necessary information to embark on your block theme development journey.
If you have any questions or encounter any issues, please let us know in the comments below.
Source: WPExplorer
