← All updates

Engineering / Field note

A WordPress theme deploy can leave the active template unchanged

Saved block-theme templates can take precedence over their matching theme files. A code release needs to account for the design state editors have already saved in the database.

By Zyel · Published · 4 min read

A WordPress block-theme file can arrive on the server exactly as intended while the public page continues to use a saved customization. WordPress stores templates edited through its visual interface in the database, where they can take precedence over the matching template in the theme. That makes the effective design a combination of shipped files and saved site state. [1]

This is established platform behavior, documented in the Theme Handbook’s Templates chapter published in October 2023. It remains an operational concern when a team treats a theme release as a complete description of the design visitors will receive. [1]

The selected template has a source

WordPress chooses templates according to the requested page type and its template hierarchy. For block templates, the documented source priority includes user-created database templates, then an active child theme’s templates, then the theme’s templates. The hierarchy also distinguishes front pages, individual posts, archives and other page types. The template identity being selected matters alongside where its contents are stored. [2]

As a hypothetical example, imagine a publication whose editor customized the standard single-post template to add a membership notice. Later, a developer changes that same template in the theme to improve its layout. The new file can be present while the saved single-post customization remains the effective version. This describes a possible configuration state, rather than an incident at a named publication.

Our interpretation is that the release has two acceptance questions. Did the intended artifact reach the environment? And does the intended page use the reviewed design? A positive answer to the first question does not establish the second. The distinction becomes useful before anyone starts rebuilding a cache or repeating an otherwise successful file transfer.

The Site Editor supports changes to site-wide areas as well as individual templates. WordPress’s documentation notes that changes to shared header or footer templates affect all pages using them. Saving through that interface is therefore capable of changing the scope of the public design beyond the page an editor happened to be viewing. [3]

Editorial changes need a route into release ownership

The Theme Handbook says saved editor customizations reside in the database. It also describes copying their block markup into matching theme files when the design needs to be distributed with a theme. The Site Editor separately offers a theme export containing updated templates, template parts and style settings. [1] [3]

Those facilities give a team ways to capture work, but they do not decide which version the organization wants to own. In our view, the important agreement is whether a particular design change is local to this site, intended for the shared theme, or awaiting review. Without that agreement, a later release can preserve an accidental difference just as faithfully as an intentional one.

Consider the editor’s perspective in the hypothetical publication. The membership notice may contain an approved layout adjustment that the developer has never seen. Removing the saved customization wholesale could discard that work. Keeping it indefinitely could conceal the new layout. The engineering task is to reconcile those intentions and retain a reviewable record of the accepted result.

The same issue appears during rollback. Our assessment is that restoring older theme files only restores one part of the design state. A useful recovery plan identifies the relevant saved customizations and the approved version they represent. It should also distinguish a narrow design recovery from restoring an entire database that contains newer editorial work.

Verify the page state the visitor receives

Template hierarchy gives this review a concrete shape. The official documentation defines different matching sequences for different request types. A front page and an individual article can resolve through different templates, so a visual check of one route establishes limited evidence about another. Representative page types belong in release acceptance. [2]

Our practical interpretation is to connect the reviewed change with the affected template, its effective source and a rendered example of the relevant page type. That gives the next maintainer a reason for the result they see. It also makes an intentional editor override visible without treating normal editorial flexibility as an error.

There is room for both a maintained theme and controlled visual editing. The useful boundary is ownership: who can change a shared design, how that work becomes reviewable, and which version should win after a release. Once that is explicit, a theme deployment can be judged against the design it was meant to deliver, with fewer mysteries left in the database.

Sources + further reading

Source dates describe the original material. Publication above is the date this Zyel article went live.

  1. Templates: resolution and saved customizationsWordPress Theme Handbook · Checked Nov 14, 2026
  2. Template HierarchyWordPress Theme Handbook · Checked Nov 14, 2026
  3. Site Editor and theme exportWordPress Documentation · Checked Nov 14, 2026

Reader discussion

What would you ask next?

Questions, useful corrections and thoughtful disagreement are welcome. Comments are reviewed before they appear.

No reader comments yet.

10–2,000 characters. Plain text. Leave out passwords, private project data and personal contact details. A blank display name appears as Anonymous.

Complete the CAPTCHA before sending. Verification runs on your device.