Skip to content

Pages

Pages are file-based templates that sync to the WordPress database as posts. Synchronization is explicit: run wp bs pages sync or call the Pages API when you intend to apply source changes. Loading the frontend or WordPress admin never performs complete page discovery or mutates page posts.

Pages can be defined as a single page.json folder, as standalone Markdown, or as a collection with a pages.json manifest. Collections are useful for documentation, knowledge bases, landing page libraries, or any set of nested pages that should be generated from files.

page.json

For a JSON-defined page, add a page.json configuration file:

JSON
{
  "name": "about",
  "title": "About Us",
  "slug": "about-us",
  "postType": "page",
  "postStatus": "publish",
  "templateLock": "all"
}

Properties

Property Type Default Description
name string required Unique identifier for the page
title string Auto from name The page title
slug string Same as name URL slug for the page
path string "." Logical path inside a collection
order integer 0 Menu order for the synced post
postType string "page" WordPress post type
postStatus string "draft" Status for new posts (publish, draft, pending, private)
postId integer – Pin the page to a specific WordPress post ID
blockEditingMode string – Block editing mode: "default", "contentOnly", or "disabled"
templateLock string|false "all" Lock mode: "all", "insert", "contentOnly", or false
templateFor string|null null Set as default template for a post type
sync boolean true Whether normal explicit reconciliation may create or update the post
render string|object|false – Render the page with a registered page renderer (see Component Pages)

Across page.json, frontmatter, and loader entries, recognized keys include blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock, and title. Any key not listed above is stored under the page’s meta array.

Content Sources

A page definition decides which WordPress post should exist. The content source decides which block markup is written to that post.

When a page folder has a page.json, Blockstudio looks for a sibling source file in this order:

File Use
index.php HTML-like block markup, read as-is (PHP code is not executed)
index.blade.php Blade template content
index.twig Twig template content
index.md Markdown content

page.json can also provide inline markdown or html instead of a sibling file:

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "name": "notice",
  "title": "Notice",
  "html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}

Collections add two more source modes:

  • Markdown files discovered directly from the collection tree.
  • Loader entries returned from loader.php.

Loader entries can use markdown, html, or content with contentType. They can also point at a local file or template. File and template sources infer their type from the extension unless contentType is set explicitly.

Supported contentType values are php, blade, twig, markdown, and html. Markdown is converted to HTML first, then parsed into native WordPress blocks. PHP, Blade, Twig, and HTML sources go through the normal Blockstudio page parser.

Classes on core blocks

A class on an HTML element mapped to a core block becomes its className. An explicit core block tag can use className directly. Both forms preserve the classes on the block’s saved wrapper, alongside the classes WordPress generates:

HTML
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
  <h2 class="title">Feature</h2>
</block>

If both properties are present, className takes precedence. This conversion only applies to core blocks: a custom block mapping keeps its class field unchanged. Button style classes, such as is-style-outline, belong to the button wrapper, not its link.

Run wp bs pages sync to apply parser corrections to previously synced pages. Parser upgrades are recognized by the next explicit sync without a source-file edit. Locked pages and pages with sync: false retain their normal protections; frontend requests never perform this synchronization.

Serialized WordPress blocks

Page and pattern sources can also contain serialized blocks copied from the WordPress code editor:

HTML
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->

When the source contains a <!-- wp:... --> block delimiter, Blockstudio uses WordPress’s native block parser for the entire source. Attributes, nested blocks, dynamic blocks such as Query Loop, and Blockstudio blocks keep their serialized structure. HTML outside the block comments stays native freeform HTML; it is not mapped into additional blocks. Do not mix Blockstudio’s HTML block tags with this format and expect them to be converted. Ordinary HTML comments do not select serialized-block mode.

Markdown Pages

Use Markdown when prose should live in files but still become editable WordPress block content after sync. Markdown source is converted to block markup during sync. The synced post stores blocks, not the raw Markdown body.

Markdown can be used in three ways:

Source Frontmatter required? Notes
Standalone pages/example/index.md Yes Frontmatter provides the page identity.
page.json plus index.md No page.json defines the page and Markdown provides content.
Markdown inside a collection No The collection infers name and path from the file location.

A standalone index.md without frontmatter is skipped because Blockstudio has no page identity to sync. Collection Markdown does not need frontmatter because the collection manifest and file path provide that identity.

Markdown
---
name: about
title: About
slug: about
postStatus: publish
---

# About

This Markdown content is synced as native WordPress blocks.

You can also pair page.json with index.md. In that case, page.json defines the page and index.md provides the content. Frontmatter in index.md overrides matching page.json values.

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
title: API Reference
order: 20
---

# Reference

This page uses `page.json` with Markdown content.

For collection Markdown, the file path becomes the logical page path unless frontmatter overrides it:

File Default path
pages/docs/index.md .
pages/docs/getting-started.md getting-started
pages/docs/guide/install/index.md guide/install
pages/docs/guide/install.md guide/install

Unknown frontmatter keys are preserved in the page’s meta array. This lets you attach data such as section or description and read it from the PHP API.

Markdown is parsed as GitHub Flavored Markdown. Raw HTML is allowed, unsafe links are stripped, and headings without an explicit ID receive a stable one. Nested YAML frontmatter requires the bundled YAML parser.

Raw Markdown

Markdown file sources can expose their original source Markdown for external tools and documentation consumers. Inline Markdown does not have a source file, so it syncs to blocks but does not produce a raw .md response.

Request the page with a .md suffix, such as https://example.com/docs/reference.md. Or send an Accept: text/markdown header to the normal page URL:

Shell
curl -H "Accept: text/markdown" https://example.com/docs/reference/

Frontmatter is removed from the response. Successful raw Markdown responses send Content-Type: text/markdown, X-Robots-Tag: noindex, and a canonical Link header back to the HTML page. Missing .md routes return a real 404.

Negotiation works with static prerendering: a request whose Accept header contains text/markdown is never answered from the prerender store or the early-serve drop-in, so it reaches WordPress and the Markdown handler. Prerendered HTML responses, the HTML of a page that also negotiates Markdown, and the Markdown answered through Accept send Vary: Accept, so caches that honour Vary keep the two apart. A CDN that keys its cache on the URL alone needs its own rule to bypass the cache for such requests. Pages::negotiates_markdown( $post_id ) reports whether a page answers Markdown requests.

Collection Markdown keeps the same URL shape for raw Markdown:

Page URL Raw Markdown URL
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

Disable raw Markdown responses with the blockstudio/pages/serve_markdown filter:

PHP
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );

A .md URL that does not resolve to a Markdown-backed page returns a 404 only when the path falls inside a page collection. Outside every collection, Blockstudio leaves the request alone for WordPress and other plugins to handle.

Component Pages

A component page is rendered by a page renderer instead of being stored as blocks. Blockstudio does not ship a renderer. A theme or plugin registers one for the entry files it handles, such as a React renderer for page.tsx, and Blockstudio calls it with the page, the WordPress post, and the rendered slot content.

Text
pages/legal-notice/
  page.json
  page.tsx
  data.php
JSON
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}

render is explicit. A directory with an index.php and a page.tsx but no render stays an ordinary page, so adding a renderer never renders an existing page twice. The forms are:

Value Meaning
"page.tsx" Entry only, without a data loader
{ "entry": "page.tsx", "data": "data.php" } Entry and data loader
{ "entry": "page.tsx", "renderer": "react" } Entry with an explicit renderer id
false No renderer, even when a collection default names one

Paths resolve against the page directory, or against the collection root for loader entries. They must stay inside the discovery source unless blockstudio/pages/allow_external_loader_path allows them. Without renderer, the renderer that claims the entry’s extension is used. A render that names a missing entry or data file, an unknown renderer, or an extension no renderer claims is a discovery error, which fails the reconciliation before anything is pruned.

What sync stores

Sync stores one blockstudio/page block. When the page directory also has an index.* source, that source is parsed as any page source and becomes the block’s inner blocks, its slot:

HTML
<!-- wp:blockstudio/page /-->

<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->

Keep WordPress-owned content, such as shortcodes, in the slot. A source that is only one shortcode, such as [download_checkout], is stored as a core/shortcode block, so its output gets no paragraph around it. It stays in post_content, so has_shortcode() checks see it, keyed slot blocks merge with editor changes as nested keyed blocks do, and do_shortcode expands the shortcodes once at its usual the_content priority, after the renderer framed them.

The render definition is stored with the post as portable theme: paths. The page fingerprint covers the definition, not the bytes of the entry or data loader: editing page.tsx or data.php leaves the post unchanged and reaches visitors through rendering and the static prerender graph, which records the entry, the data loader, and every file the renderer reports.

Registering a renderer

Register renderers on the blockstudio/pages/renderers action. It fires once per request, before the first discovery or render, so wp bs pages sync and frontend requests see the same registry.

PHP
add_action(
	'blockstudio/pages/renderers',
	static function (): void {
		Blockstudio\Page_Renderers::register(
			'react',
			array(
				'extensions' => array( 'tsx' ),
				'layouts'    => array( 'layout.tsx' ),
				'render'     => 'my_theme_render_page',
			)
		);
	}
);

Renderer ids are lowercase. An extension or layout name can belong to one renderer only, and layout.php stays Blockstudio’s own layout. The callable receives one request:

Key Value
kind page, or layout for a renderer layout
renderer Renderer id
entry Absolute entry path
data Absolute data loader path, or null
page Canonical page data, including meta
post_id WordPress post ID
slot Rendered slot content, or the page content for a layout
context frontend, rest, feed, or cli

It returns the HTML, the files the render read, and optional assets:

PHP
function my_theme_render_page( array $request ): array {
	return array(
		'html'         => '<main>...</main>',
		'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
		'assets'       => array( array( 'path' => '/abs/path/to/page.js' ) ),
	);
}

context comes from the request type and never from the visitor, so a renderer cannot break logged-in and anonymous byte parity by reading it. A renderer that fails throws: the page does not render an empty body. In a REST editor preview the block shows the error as a notice instead. After a successful render the blockstudio/pages/rendered action receives the page, the HTML, and its dependencies.

assets lists script and style files the page needs. They get the processing of block assets (the *.inline.* convention, ES modules, minification and ?ver), and the page prints them once, through the same buffer that prints block assets, so a prerendered page carries them. An asset may set version to replace its ?ver value. Code outside a renderer can use the same channel through Blockstudio\Assets::register_owner(), which returns the marker comment to print.

Editor

In the editor, blockstudio/page shows a server-rendered preview of the page with the slot as inner blocks, which follow the page’s templateLock. The block cannot be inserted, duplicated, or nested in another block.

Page Collections

A collection is a folder with a pages.json manifest. It groups many page sources under one collection slug, applies defaults, supports nested paths, and can register a dedicated post type automatically.

Code
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
Property Type Description
collection / slug / name string Collection slug. collection is the clearest form and becomes the public URL base.
title string Human-readable collection title.
postType string Post type for generated pages. Defaults to page. If it does not exist, Blockstudio registers it.
postTypeArgs object Arguments passed to register_post_type() when Blockstudio registers the collection post type.
defaults object Default page properties applied to every page in the collection. A default render applies to a page only when its entry exists in the page directory.
scope string collection (default) or site. See Site Collections.
meta object Custom collection metadata. Unknown manifest keys are also stored in meta.

Collection page paths are logical paths. A page with path: "guide/install" is synced as a child of guide, and guide is synced as a child of the collection root when those parent pages exist.

If a hierarchical collection has a nested page but an intermediate parent source does not exist, Blockstudio generates an empty container page for that path, which keeps the WordPress hierarchy complete. Non-hierarchical post types (those without page-attributes parent support) do not generate empty containers. They route by the stored collection path, so nested paths such as guide/install and setup/install can coexist even though both end in install.

Collection Post Types and URLs

Set postType on the collection manifest to sync every page in the collection to that post type. You do not need to repeat the same value inside defaults. Individual pages can still override postType in frontmatter or page.json.

When the post type does not exist, Blockstudio registers it with show_in_rest: true, a page-like editor setup, and the collection slug as the public URL base. postTypeArgs can override the registration arguments. Collection post type rewrite rules are flushed automatically when the registered collection post types or rewrite args change, so you do not need to resave WordPress permalinks.

Collection URLs use the collection slug plus each page’s logical path:

Source path Public URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

This URL model works for both hierarchical and non-hierarchical collection post types. Blockstudio also redirects doubled URLs such as /docs/docs/ or /docs/docs/getting-started/ to the canonical URL.

Collection pages expose raw Markdown at the same URLs (see Raw Markdown).

If you change a collection from postType: "page" to a custom post type, Blockstudio migrates already synced collection posts in place when their stored page identity matches. That preserves post IDs, metadata, and existing content while avoiding duplicate old-typed posts. Stale collection posts are cleaned up across all post statuses according to the blockstudio/pages/orphan_action filter.

Site Collections

A manifest with "scope": "site" groups every page below it without turning them into collection pages. Use it at the root of a site’s pages tree to apply shared defaults and to list the site’s pages with blockstudio_page_tree( 'my-site' ).

JSON
{
  "collection": "my-site",
  "title": "My Site",
  "scope": "site",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "all",
    "render": { "entry": "page.tsx", "data": "data.php" }
  }
}

Pages of a site collection keep exactly the identity they have without the manifest, so adding one to an existing tree updates no post rows and creates or trashes nothing:

  • Keys stay global: Pages::get_page( 'home' ) and stored page keys keep matching.
  • URLs stay WordPress page URLs. No collection rewrite rules, permalink filter, or doubled-URL redirect apply, and no empty container pages are generated.
  • Logical paths, slugs, parents, and source identities are those of standalone pages, and layouts resolve by nearest ancestor.
  • Nested pages.json manifests keep their own collections, and their subtrees are left out of the site collection.
  • Defaults apply per page: a default render applies only to pages whose directory holds its entry, so shortcode and Markdown pages keep their sources.

Collection Loaders

Collections can include a trusted local loader.php. Use it when collection pages come from another local source, such as an external docs folder, a package, or a generated manifest.

The loader runs during explicit page discovery and synchronization. It should be deterministic and local. Avoid fetching remote content from loader.php, because it would make deployment synchronization depend on that service.

PHP
<?php

return array(
  'meta' => array(
    'source' => 'loader',
  ),
  'paths' => array(
    __DIR__ . '/external-docs',
    array(
      'path' => __DIR__ . '/cli-docs',
      'prefix' => 'cli',
      'meta' => array(
        'doc_set' => 'cli',
      ),
    ),
  ),
  'pages' => array(
    array(
      'name' => 'docs-api',
      'title' => 'API',
      'path' => 'api',
      'content' => "# API\n\nGenerated markdown content.",
      'contentType' => 'markdown',
    ),
    array(
      'name' => 'docs-template',
      'title' => 'Template',
      'path' => 'template',
      'file' => __DIR__ . '/template.md',
    ),
  ),
);

A loader can return an array with pages, meta, and paths keys:

Key Description
pages A list of page arrays. Each page supports the same recognized keys as page.json and Markdown frontmatter.
meta Metadata merged into every loader-generated page’s meta array.
paths Extra local directories to discover as part of this collection. Entries can be strings or path objects.
render A render definition for every Markdown page discovered from paths.

As a shorthand, the loader may return a bare list of page arrays.

Loader page entries can provide content in these ways:

Shape Description
markdown Inline Markdown content.
html Inline HTML content.
content + contentType Generic inline content. contentType must resolve to markdown or html.
file Local file source. Type is inferred from the extension unless contentType is set.
template Alias for file.

Loader file references can point to PHP, Blade, Twig, Markdown, or HTML sources. Relative paths resolve from the collection root. Absolute paths and paths outside the collection root are allowed only when the blockstudio/pages/allow_external_loader_path filter permits them.

Loader pages default to generated: true. When a generated loader page disappears from loader output, Blockstudio treats the synced post as an orphan on the next sync, cleaned up according to the blockstudio/pages/orphan_action filter.

Directories listed in paths are discovered like normal collection folders. They can contain Markdown files or page.json folders. If those paths are outside the collection root, the same external path filter applies.

Use a string entry when the external directory should keep its own logical paths. Use an object entry when the directory should be mounted under a collection path prefix:

PHP
'paths' => array(
  array(
    'path' => __DIR__ . '/cli-docs',
    'prefix' => 'cli',
    'meta' => array(
      'doc_set' => 'cli',
    ),
  ),
),

With that configuration, cli-docs/index.md becomes path: "cli" and cli-docs/getting-started.md becomes path: "cli/getting-started" in the collection. Prefixes also make generated page names collision-safe, so multiple mounted directories can each contain index.md or getting-started.md. Set preserveNames to true on the path object if explicit name values from page.json or Markdown frontmatter should be kept instead.

Path object properties:

Property Type Description
path string Local directory to discover. Relative paths resolve from the collection root.
prefix string Optional logical path prefix inside the collection.
preserveNames boolean Keep explicit page names instead of generating names from the prefixed path. Defaults to false when prefix is set.
meta object Metadata merged into every page discovered from this path. Page-level metadata wins on duplicate keys.
render string|object A render definition for the Markdown pages of this path, overriding the loader’s render.

Rendering Markdown through a component

With render, the Markdown pages a loader discovers render through a page renderer instead of being stored as blocks:

PHP
<?php

return array(
  'paths'  => array( __DIR__ . '/external-docs' ),
  'render' => array(
    'entry' => __DIR__ . '/document.tsx',
    'data'  => __DIR__ . '/document.php',
  ),
);

They stay Markdown pages: the content type, the content path, the .md responses and the frontmatter are unchanged. Sync stores one blockstudio/page block whose inner HTML is the converted Markdown, sanitized when the collection sanitizes its content, instead of parsed blocks, so post_content keeps the document text. The renderer receives that HTML as the slot and can read the source from page.content_path. Relative paths resolve from the collection root; the external path filter applies as for the paths. A page whose frontmatter sets its own render, or render: false, is left out.

Layouts

A layout.php file wraps the frontend rendering of a file-based page. It does not replace the synced post_content stored in WordPress, and it does not wrap the editor canvas. The layout only runs on singular frontend requests.

For collections, put layout.php next to pages.json to wrap every frontend page in that collection:

PHP
<?php $current = blockstudio_current_page(); ?>

<main class="docs-layout">
  <aside>
    <?php foreach (blockstudio_page_tree('docs') as $item) : ?>
      <?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
      <a
        href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
        <?php echo $is_current ? 'aria-current="page"' : ''; ?>
      >
        <?php echo esc_html($item['title']); ?>
      </a>
    <?php endforeach; ?>
  </aside>

  <article>
    <?php echo blockstudio_page_content(); ?>
  </article>
</main>

blockstudio_page_content() prints the page body that WordPress would normally render through the_content. If a layout does not output blockstudio_page_content(), the page content is intentionally hidden.

Layouts can use the page helper functions:

PHP
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();

Nested non-collection pages can also inherit the nearest ancestor layout.php inside the pages tree. For collection pages, the collection root layout is stored on each synced post and watched as part of the page fingerprint, so layout changes are picked up on the next sync.

Renderer Layouts

A layout can also be a renderer entry, such as layout.tsx for a renderer that registers layouts: ["layout.tsx"]. It is found in the same places as layout.php, and an optional layout.data.php beside it is its data loader. At render time the renderer receives kind: "layout" and the rendered page content as slot, at the same the_content priority as layout.php. A directory may hold layout.php or one renderer layout, not both; holding both is a discovery error. A layout failure fires blockstudio/pages/layout_error and leaves the page content unwrapped, as it does for layout.php.

Block Editing Mode

The blockEditingMode property controls how blocks can be edited in the editor. Set a page-level default in page.json and override per-element in the template:

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>
Value Description
"default" Full editing. Blocks can be selected, moved, and edited
"contentOnly" Text editing only. Block text is editable but settings and structure are locked
"disabled" No editing. Blocks are completely non-interactive

Per-element overrides are set as HTML attributes on any element (<h1>, <p>, <div>, etc.) or on <block> elements. Ancestor container blocks of overridden elements are automatically set to contentOnly so their children remain accessible. This cascade walks up from the overridden element to the page root, so you only need to set blockEditingMode on the elements you want to make editable.

Template Lock

The templateLock property controls how users can edit the page in the editor:

Value Add/Remove Move Edit Content
"all" No No No
"insert" No Yes Yes
"contentOnly" No No Yes
false Yes Yes Yes

When a templateLock is set, Blockstudio disables the ability to unlock blocks via the editor UI.

Virtual Routes

Some documents have no post behind them: a component reference generated from data, a catalog, or an account area. Register them as virtual routes instead of hooking template_redirect yourself:

PHP
add_action( 'init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function ( $component, string $rest ) {
            get_header();
            echo my_component_page( $component );
            get_footer();
        },
        [
            'prefix' => true,
            'match'  => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
            'title'  => fn ( $component ) => my_component_title( $component ),
            'urls'   => fn () => my_component_paths(),
        ]
    );
} );

The path is relative to the site home. With prefix, the route also serves every path below it, and match receives that remainder (an empty string for the route itself) and returns the value the render callback receives, or null to leave the URL to WordPress, which then answers 404 as usual. The render callback echoes the document or returns it as a string; title is a string or a closure that receives the match value.

For a matched request Blockstudio keeps WordPress from flagging a 404 and redirect_canonical from redirecting it, clears the singular state the main query reports, sends the status (status, 200 by default), and renders at template_redirect priority Virtual_Routes::PRIORITY. That is right after Blockstudio’s output buffer opens at Assets::BUFFER_PRIORITY, so the finished document gets its block assets, bundled UI assets, and compiled Tailwind like any page, and before redirect_canonical at priority 10. A handler that renders a whole document on its own must also run after Assets::BUFFER_PRIORITY, or that processing is skipped. The paths in urls (by default the route path itself, when it is not a prefix route) are added to static prerender builds, and Virtual_Routes::urls() returns them as absolute URLs for a sitemap. Virtual_Routes::match( $path ) resolves a path the way a request would.

Sync Behavior

Page posts change only through an explicit synchronization operation:

Shell
wp bs pages sync

The command discovers the complete source inventory, creates or updates changed posts, prunes confirmed orphans, refreshes collection routing and compiled templateFor configuration, and reports what changed. Add --authoritative to replace managed content instead of preserving keyed editor content, and --full to report the pass as a full reconciliation regardless of the stored source identity:

Shell
wp bs pages sync --authoritative --full

Normal frontend, admin, AJAX, REST, cron, and generic WP-CLI bootstrap requests do not run complete page discovery, query the managed reconciliation inventory, or write page posts. They use already-synced WordPress posts plus compact collection and post-type-template configuration persisted by the last explicit operation. A cold installation or upgrade may scan collection manifests once to restore routing metadata; that read-only bootstrap never synchronizes content. The authenticated, opt-in Canvas refresh endpoint is an explicit authoring API: Canvas calls it once when the workspace opens so newly added or changed sources appear in the initial inventory. Live mode calls the same boundary when it observes a page-source change.

Blockstudio\Pages::init() now registers request-time hooks only. Integrations that previously passed a force argument to that method must call Blockstudio\Pages::reconcile() or run wp bs pages sync instead.

To prevent a page from being overwritten after manual edits, set "sync": false in page.json.

Portable Source Locations

Synced theme files are stored as theme-relative locations rather than absolute installation paths. Child-theme files and parent-theme files keep separate identities, even when they have the same relative filename. Page helpers still return resolved absolute template_path, content_path, layout_path, and directory values for the current request.

This lets CLI synchronization and web requests use different filesystem roots, as on jailed hosting, without breaking Markdown responses, layouts, editor Tailwind scanning, or prerender source tracking. Existing absolute theme paths are rebased on read when the theme directory name is unchanged. No sync, database migration, or request-time metadata write is required to read them; the next explicit sync stores the portable locations.

A theme directory that is a symlink, for example into a development checkout, stores the same theme: locations whether a source was read through the symlink or through its target, and resolves them to the configured theme directory.

Files outside the active child and parent themes remain supported at their configured absolute paths, subject to PHP’s open_basedir restrictions. They are not automatically relocatable: after moving an external source, update its configured path and run an explicit sync.

Post Field Ownership

postStatus sets the initial status. Subsequent syncs preserve existing draft, pending, private, published, and scheduled statuses, including with --authoritative. A draft is not republished just because its file says postStatus: "publish". The existing orphan-recovery behavior is unchanged: an explicit sync restores a trashed managed post when its source is present. Lock the page or disable sync to prevent that restoration.

The file continues to own the title, slug, post type, parent, and configured menu order. Editing those in WordPress does not change the source definition. The next explicit sync reapplies the file values and names the affected fields in pages.<name>.overwritten, with a warning in CLI table output. WordPress’s native permissions still apply, including its empty slug for pending posts when the syncing user cannot publish them.

Use blockstudio/pages/update_post_data for an integration that explicitly owns a different status policy. Keyed blocks preserve editor-owned block content; keys do not change ownership of the post’s title or slug.

For collection pages, fingerprints cover the manifest, loader, page source, layout file, metadata, and related source paths. The next explicit synchronization applies changes to those inputs.

When a collection source is removed, Blockstudio removes the generated page so old collection pages do not linger after the source file is gone. By default, orphaned collection pages are moved to trash. Use blockstudio/pages/orphan_action to return trash, delete, or keep.

On frontend requests, Blockstudio hydrates the page registry from already synced published posts. Draft and private pages are available in admin and sync contexts, but frontend helpers only hydrate published pages.

Deployment Reconciliation

Blockstudio\Pages::reconcile() is the PHP deployment entry point. It discovers the complete desired inventory, compares source and sync-engine fingerprints, and returns a machine-readable report:

PHP
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
  'renames' => [
    [
      'from' => 'pages/old/index.php',
      'to' => 'pages/new/index.php',
    ],
  ],
]);

The report contains discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, per-page results, discovery errors, and a deterministic sourceIdentity.

Locked pages have status: "locked" and are counted separately from unchanged pages. removedPages lists each removed page’s name, key, postId, and actual action (trash or delete); kept or already-trashed posts are not counted as newly removed. CLI table output also names created, updated, locked, removed, and content-preserved pages with their post IDs.

After parsing and keyed merging, an identical final post does not call wp_update_post(), change post_modified, create a revision, or fire post update hooks. Its result is unchanged. When the source’s content differs from the editor-owned keyed content, preserved: true identifies that decision and the top-level preserved count includes it. The new source fingerprint and managed metadata are still recorded so the next unchanged sync is a no-op. preserved is an additional flag, not an exclusive status: a page may preserve keyed content while still updating a file-owned title or adding another block.

authoritative: true may clear a Page Sync lock and replaces content from the file definition instead of preserving keyed editor content. Leave it false for a normal explicit synchronization. plan_valid: false, full: true, broad: true, a missing previous source identity, or a changed sync-engine fingerprint marks the pass as a full reconciliation (fullReconciliation in the report). Every pass compares the complete inventory either way. Git rename records are identity hints only. They never replace complete inventory comparison.

Equal fingerprints with unchanged runtime paths perform no post or postmeta writes and do not fire update hooks. When an unchanged source moves into a new release directory, reconciliation refreshes only its persisted template, content, layout, and directory paths; it does not update post_content or the post-modified timestamp. Missing managed pages are pruned only after the complete reconciliation pass finishes without discovery or page-write errors.

Direct API reconciliation does not mark a deployment successful. After activating and verifying the matching static artifact and routes, persist the returned identity explicitly:

PHP
Blockstudio\Pages::store_successful_source_identity(
  $report['sourceIdentity']
);

wp bs pages sync stores the returned identity after a successful pass. Ordinary WP-CLI bootstrap only registers persisted collection post types and rewrites. It does not discover or synchronize pages.

Post ID Pinning

By default, WordPress auto-assigns post IDs. If a page is deleted and re-created, the ID changes, breaking external references like menus or hardcoded links.

Use postId to pin a page to a specific ID:

JSON
{
  "name": "about",
  "title": "About Us",
  "postId": 42
}

When creating the page, Blockstudio passes the ID to WordPress via import_id. If the ID is available, WordPress uses it exactly. If the ID is already taken by an unrelated post, WordPress silently auto-assigns a new ID.

When looking up existing pages, Blockstudio checks the pinned ID first, before checking meta or slug. This means if a page is deleted and re-synced, it reclaims the same ID.

Keyed Block Merging

By default, when a template file changes, Blockstudio replaces the entire post content with the new template. This means any edits made in the WordPress editor are lost.

Add a key attribute to blocks to preserve user edits across template syncs. When a template has keyed blocks, Blockstudio merges template changes with the existing post content instead of replacing it.

Adding Keys

Use the key attribute on any HTML element or <block> element:

HTML
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>

<div key="features">
  <p>First feature.</p>
  <p>Second feature.</p>
</div>

<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h2>Hero Title</h2>
  <p>Hero description.</p>
</block>

<block
  name="acme/testimonial"
  key="featured-quote"
  quote="Default quote"
/>

Keys must be globally unique across the entire template. A key protects the entire block and all of its content. You don’t need to key individual children inside a keyed parent. Keyed blocks can be moved to any position or nesting level between template updates and their user content will still be preserved.

Keys work the same way for Blockstudio custom blocks. The key is structural Page Sync metadata; custom field values remain normal Blockstudio attributes. When an editor changes those fields, a later template sync keeps the editor values while still applying independent template changes. Pages created by older versions with the key inside the custom field data are migrated automatically on the next sync.

How Merging Works

When a template file changes and the page re-syncs:

Block Behavior
Keyed block User content and Blockstudio field values are preserved. Template-owned attributes and structure are applied.
Unkeyed block Replaced entirely with the template version (same as without keys)

Examples

User edits are preserved in keyed blocks:

  1. Template defines <p key="intro">Default intro.</p>
  2. User edits the paragraph in the editor to "Custom intro text."
  3. Developer updates the template, adds a new block, changes layout
  4. On sync: the paragraph keeps "Custom intro text." while the new layout is applied

Attributes from the template still apply:

  1. Template has a cover block with key="hero" and a url attribute
  2. Developer changes the cover’s url attribute to a new background image
  3. On sync: the new background image is applied, but user’s content edits inside the cover are preserved

Edge Cases

Scenario Behavior
New keyed block added to template Appears with the template’s default content
Keyed block removed from template Deleted from the post
Block type changes (same key) Template wins entirely, no content merge
Duplicate keys Second occurrence is treated as unkeyed
No keys in template Full replacement (same behavior as without keys)
Force sync Full replacement, keys are ignored
Locked post No sync at all

Combining with Editing Controls

Keys, templateLock, and blockEditingMode combine to give you fine-grained control over what clients can and can’t do. Here are common workflow patterns.

Fully locked page

The developer controls everything. The page is a static layout that clients can’t touch at all. Useful for legal pages, terms of service, or any page that should only change through code.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>

No keys needed. The template is the single source of truth. Every sync overwrites the page entirely.

Locked layout with editable content

The most common pattern. Lock the page structure so clients can’t add, remove, or rearrange blocks, but let them edit text in specific places. Keys ensure their edits survive template updates.

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Title</h1>
  <p blockEditingMode="contentOnly">Edit this description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">Contact Us</block>
</block>

The client can edit the hero title, description, and feature intro. Nothing else. The button text, URL, and cover background image are developer-controlled. When the developer updates the template (e.g., adds a second button), keyed sections keep the client’s text.

Evolving template with preserved content

For pages that grow over time. The developer adds new sections to the template, and each sync adds the new content without touching what the client has already customized.

HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
<div key="testimonials">
  <h2>Testimonials</h2>
  <p>What our clients say.</p>
</div>
<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
</block>

The new testimonials section and button appear on sync. The client’s edits to the title, intro, and services are untouched.

One-time scaffold

Create a page with a starting structure, then hand it off entirely. Set sync to false so normal synchronization never creates or updates the page, and create it once with Blockstudio\Pages::force_sync('blog'). After that, the client owns the page completely.

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>

wp bs pages sync skips this page, so force_sync() creates it once. After that, the client can add, remove, and rearrange blocks freely. Template changes are ignored.

Block Bindings

An alternative to keyed merging is using WordPress core’s Block Bindings API to connect blocks to post meta. This is not a Blockstudio feature, it is a native WordPress API. Blockstudio simply passes the metadata attribute through to the generated block markup. The content lives in post meta instead of block markup, so template syncs can freely overwrite the markup because the editor reads from meta, not from innerHTML.

Pass the metadata attribute on any HTML element or <block> element:

HTML
<h1
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
  Default Title
</h1>

<p
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
  Default description text.
</p>

<img
  metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>

The meta keys must be registered with show_in_rest enabled:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest'  => true,
    'single'        => true,
    'type'          => 'string',
    'default'       => 'Default Title',
) );

Keys vs. bindings

Aspect Keys Bindings
Content stored in Block markup (post_content) Post meta (wp_postmeta)
Survives template sync Yes (merged by key) Yes (data lives in meta)
Queryable via WP_Query No Yes (meta_query)
Available in REST API No Yes
Requires registration No Yes (register_post_meta)
User can move blocks No (template re-imposes structure) No (template re-imposes structure)

Both approaches can be used in the same template. Use keys for sections where the block structure matters (e.g., a group with multiple children). Use bindings for individual fields where you also want the data accessible outside the block editor.

Post Type Templates

Use templateFor to set a page as the default template for a post type:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}

Any new posts of that type will start with the defined block structure.

Custom Paths

By default, Blockstudio scans get_template_directory() . '/pages'. Add additional paths with the filter:

PHP
add_filter( 'blockstudio/pages/paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/custom-pages';
    $paths[] = MY_PLUGIN_DIR . '/pages';
    return $paths;
} );

Runtime integrations that compose files from several roots can replace the filesystem scan with a logical discovery source. Page manifests, layouts, loaders, and source templates are then resolved by logical path, even when their selected files live in different roots.

Filters and Actions

Page discovery, sync, and collection routing expose these extension points:

Hook Type Description
blockstudio/pages/paths Filter Add directories that Blockstudio scans for page sources.
blockstudio/pages/collection_post_type_args Filter Adjust register_post_type() args for a collection CPT.
blockstudio/pages/template_candidates Filter Adjust template filenames considered for a page source.
blockstudio/pages/serve_markdown Filter Enable or disable raw Markdown responses.
blockstudio/pages/orphan_action Filter Return trash, delete, or keep for orphan cleanup.
blockstudio/pages/docs_allowed_html Filter Adjust allowed HTML for generated Markdown docs content.
blockstudio/pages/allow_external_loader_path Filter Allow loader paths outside the collection root.
blockstudio/pages/manifest_scan_interval Filter Set the maximum age of a legacy pre-7.6.2 manifest cache that may seed persisted runtime configuration during an upgrade.
blockstudio/pages/create_post_data Filter Modify post data before a synced page is created.
blockstudio/pages/update_post_data Filter Modify post data before a synced page is updated.
blockstudio/pages/sync_engine_inputs Filter Add a parser, mapping, or migration version that should deliberately broaden reconciliation once.
blockstudio/pages/post_created Action Runs after a synced page post is created.
blockstudio/pages/post_updated Action Runs after a synced page post is updated.
blockstudio/pages/synced Action Runs after the page registry has finished syncing.
blockstudio/pages/reconciled Action Runs after an explicit reconciliation with its machine-readable report.
blockstudio/pages/renderers Action Register page renderers with Blockstudio\Page_Renderers::register(). Fires once per request.
blockstudio/pages/rendered Action Runs after a component page rendered, with the page, its HTML, and its dependencies.
blockstudio/pages/layout_error Action Runs when a layout cannot be rendered, with the error, the layout path, and the page.

PHP API

PHP
// Get all registered pages.
$pages = Blockstudio\Pages::pages();

// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');

// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');

// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');

// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');

// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');

// Get a specific page.
$page = Blockstudio\Pages::get_page('about');

// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');

// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');

// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();

// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);

// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);

// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');

// Unlock a page.
Blockstudio\Pages::unlock('about');

// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
  'extensions' => ['tsx'],
  'layouts' => ['layout.tsx'],
  'render' => 'my_theme_render_page',
]);

// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');

// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);

See Deployment Reconciliation for argument semantics, report fields, and the verified source identity boundary.

Global helper functions are available for templates and layouts:

PHP
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();

Page arrays returned by Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children(), and the global helpers include the synced post identity, source and template paths, collection/path metadata, content type, sync policy, post type/status, editing policy, custom metadata, and a permalink key. Collection metadata is loaded from the last successful explicit reconciliation. Normal requests reconstruct this runtime data from persisted configuration and synced post meta without reading page source trees. The Pages class does not expose a separate permalink method.

Building File-Based Pages

Template locking, block editing modes, keyed merging, and controlling what clients can edit.