WordPress | Build Branded Maintenance Pages with Block Themes
WordPress block theme creators can replace a plain maintenance message with a page that matches the rest of the website. Published on July 13, 2026, the tutorial uses a one-time theme hook and a custom Maintenance template that can later be designed, updated, activated, and removed directly through the Site Editor.
A maintenance page can remain part of the website design
Visitors sometimes reach a website while plugins, themes, content, or other parts of the project are being updated. A basic technical message communicates that the site is temporarily unavailable, but it does little to preserve the visual identity or explain what visitors should do next.
With a block theme, the maintenance experience can use the same fonts, colors, spacing, logo, patterns, and template parts as the rest of the site. This makes the temporary page feel intentional instead of looking like an error or an abandoned website.
The developer adds the routing logic only once
The setup begins with a PHP function added to the theme's functions.php file. It uses the template_include filter to check whether the current block theme contains a template named Maintenance and, when it finds one, loads that template for visitors who are not signed in.
WordPress uses locate_block_template() to find the matching design, including templates saved in the database through the Site Editor. Logged-in users bypass the maintenance page, allowing administrators and editors to continue reviewing the normal website while other visitors see the temporary message.
The Site Editor controls the visible page
After the hook is installed, the visible page can be created without editing another PHP file. Go to Appearance, open the Site Editor, select Templates, and create a template named Maintenance. WordPress assigns the maintenance slug that the hook expects.
The template can be built like any other block theme layout. It can include a logo, status message, expected return time, contact details, links, patterns, or selected header and footer template parts. Global Styles remain available, so the temporary page can use the site's established typography and color system.
Activation does not require another code change
In this implementation, the existence of the Maintenance template acts as the switch. Once the template is created with the expected name, logged-out visitors receive it across the site.
To restore the normal website, an administrator can rename or delete the template from the Site Editor. This separation is useful for teams because the developer handles the routing logic once, while editors and designers remain responsible for the message and visual presentation.
SEO-friendly headers clarify that downtime is temporary
Sites with search traffic or longer maintenance windows should use the extended version of the hook. It sends a 503 Service Unavailable status, which tells search engines that the interruption is temporary rather than a permanent removal of the website.
A Retry-After header can suggest when crawlers should return, while nocache_headers() helps prevent the temporary page from remaining stored in a CDN or proxy after maintenance ends. These headers do not change what visitors see, but they provide better technical signals during planned downtime.
IMPORTANT: This tutorial creates a custom theme-level maintenance page whenever a template named Maintenance exists. It is not automatically connected to the temporary maintenance state WordPress Core creates during plugin, theme, or Core updates. Review and test the PHP implementation before using it on a production website.{alertWarning}
Testing should include logged-in and public views
After saving the Maintenance template, log out or open the site in a private browser window. Confirm that public visitors see the temporary page, then sign in again and verify that administrators can still access the normal frontend and dashboard.
It is also worth checking the page on mobile screens, testing important links, and confirming that the normal website returns immediately after the template is renamed or removed. Sites using caching services should verify that the temporary response is not stored longer than intended.
Daisuki's Take: What This Means for Web Designers
For web designers, a maintenance page is a small part of the project, but it can strongly affect trust. Visitors should understand that the interruption is planned and temporary, not assume that the website is broken or no longer active.
We think the strongest part of this approach is the division of responsibilities. A developer prepares the technical routing, while designers and editors can maintain the actual page through familiar blocks, patterns, and Global Styles.
The practical takeaway is to prepare the template before it is urgently needed. Build the design, test the public and logged-in views, confirm the response headers, and document how the team should activate and remove it during planned site work.
Sources and Recommended Links
- On-brand maintenance mode for WordPress Block Themes | WordPress Developer Blog
- template_include hook | WordPress Developer Resources
- wp_is_maintenance_mode function | WordPress Developer Resources
