Block theme

A block theme has a templates/ folder with at least index.html, usually a parts/ folder for header and footer, a style.css for the theme header, and a theme.json for settings. WordPress detects it by the presence of templates/index.html, and Appearance > Editor appears in wp-admin instead of Customize.

Check from WP-CLI with wp theme list --fields=name,status and then look for the templates folder, or call wp_is_block_theme() in code, which returns true or false.

A restaurant site on a block theme named Bistro has templates/single.html, templates/archive.html, and parts/header.html. The owner opens Appearance > Editor, changes the header's phone link, and saves. WordPress writes a wp_template_part row to wp_posts with the post_name header; the file in parts/header.html is untouched.

When the developer later ships a theme update with a new header file, the site still shows the owner's edited version because the database copy wins. Resetting the template in the Site Editor falls back to the file.

A block theme differs from the classic theme model that theme.json now augments. Classic themes use header.php, single.php, and functions.php hooks, and Customizer widgets. A block theme drops those requirements, and theme.json carries the colors, spacing, and typography it exposes in the editor.

Calling any theme with a few blocks a block theme. Expecting widgets and the Customizer menu to appear after switching. Editing the HTML file in the theme folder and not seeing changes because a database customization overrides it. Losing user edits when switching to another block theme. Putting PHP in an .html template and wondering why it prints as text.

If you are choosing between theme types this month, build the single post and archive templates in a block theme on staging and note which plugins stop working. Export user changes with the Site Editor's export tool before switching themes.