# Full pages, defined in code

Templates and Markdown, synced to WordPress with one command.

## Collections from files

Define `pages.json` and let Blockstudio discover every source below it. Nested paths become nested pages, defaults apply to the collection, and missing parents can be generated.

Use collections for documentation, knowledge bases, or landing pages, and mount external folders under a path prefix with `loader.php`.

Put a `layout.php`, or a renderer layout such as `layout.tsx`, next to `pages.json` to wrap every page of the collection in one shell, with `blockstudio_page_tree()` for the sidebar.

[Page collections](https://blockstudio.dev/docs/pages-and-patterns/pages/#page-collections)

pages/docs/pages.json

```
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
```

## Explicit sync

wp bs pages sync applies changes; unchanged pages cost zero writes.

## Markdown sources

Use index.md with frontmatter or pair page.json with Markdown content.

## Raw Markdown

Markdown file pages answer at their URL plus .md, or at the normal URL for Accept: text/markdown, with a canonical link back to the HTML.

## Collection loaders

Mount external docs folders into a collection under a path prefix.

## Site collections

A pages.json with scope site applies shared defaults to a whole pages tree and lists it, without changing URLs or post rows.

## Navigation helpers

blockstudio_page_tree(), blockstudio_page_children(), blockstudio_current_page(), and blockstudio_page_content() build sidebars, pagers, and the body.

## Collections and post types

Collections can register dedicated hierarchical post types.

## Template locking

Lock pages or individual blocks with contentOnly, all, or insert.

## Write HTML, get blocks

Standard elements such as `<h1>`, `<p>`, and `<ul>` map to core blocks. Use `<block>` for every other block name and nesting level.

Blockstudio parses complete page layouts into real, editable WordPress blocks.

[Page syntax reference](https://blockstudio.dev/docs/pages-and-patterns/pages/)

index.php

```
<div>
  <h1 blockEditingMode="contentOnly">About Us</h1>
  <p>We build tools for WordPress developers.</p>
  <img src="/team.jpg" alt="Our team" />
</div>

<block name="core/columns">
  <block name="core/column"><h2>Our Mission</h2></block>
  <block name="core/column"><h2>Our Stack</h2></block>
</block>
```

## Pages rendered by components

Set `render` in `page.json` to an entry such as `page.tsx` and a `data.php` loader, and the page renderer your theme or plugin registers draws the whole page. Sync stores one `blockstudio/page` block, and WordPress content such as a shortcode stays in its slot.

Assets the renderer returns get the same processing as block assets and print once, so a prerendered page carries them. blockstudio.dev itself is built from component pages.

[Component pages](https://blockstudio.dev/docs/pages-and-patterns/pages/#component-pages)

pages/legal-notice/page.json

```
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}
```

## Routes without a post

`Blockstudio\Virtual_Routes::register()` serves a document that has no post behind it, such as a component reference or a catalog. With `prefix` and `match`, one registration answers a whole family of URLs, and returning `null` leaves the URL to WordPress.

The route renders inside Blockstudio’s output buffer, so its blocks get their assets and Tailwind output. Paths in `urls` join static prerender builds, and `Virtual_Routes::urls()` returns them for a sitemap.

[Virtual routes](https://blockstudio.dev/docs/pages-and-patterns/pages/#virtual-routes)

functions.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(),
        ]
    );
} );
```

## Sync when you say so

Page files change WordPress only when you ask. `wp bs pages sync` applies every changed source, keeps keyed editor content, and prunes pages whose files are gone.

Fingerprints cover manifests, loaders, layouts, and sources, so unchanged pages cost zero writes. Deploys call `Pages::reconcile()` and get a machine-readable report.

[Sync behavior](https://blockstudio.dev/docs/pages-and-patterns/pages/#sync-behavior)

Terminal

```
# Apply changed sources, keep keyed edits
wp bs pages sync

# Replace managed content from the files
wp bs pages sync --authoritative

# Compare every page and report as JSON
wp bs pages sync --full --format=json
```

## Keyed blocks preserve content

Add `key` to any block. On the next sync, keyed blocks merge template attributes with existing user content while unkeyed blocks are replaced.

Evolve structure across deployments while client content remains intact.

[Keyed blocks](https://blockstudio.dev/docs/pages-and-patterns/pages/#keyed-block-merging)

index.php

```
<h1 key="title">About Us</h1>
<block name="core/cover" key="hero" url="/hero.jpg">
  <h2>Welcome to our company</h2>
  <p>Edit this content freely.</p>
</block>
<block name="core/columns" key="team">
  <block name="core/column"><h3>Our Team</h3></block>
</block>
```

## Template locking and editing modes

`"all"` prevents changes, `"contentOnly"` locks structure while allowing text edits, and `"insert"` allows editing/reordering without adding or removing.

Override any element with `blockEditingMode` to make a locked page selectively editable or disable an individual block.

[Template locking](https://blockstudio.dev/docs/pages-and-patterns/pages/#template-lock)

index.php

```
<h1>Welcome to Our Product</h1>
<p>The best solution for your needs.</p>
<block name="core/cover" blockEditingMode="disabled" url="/static-banner.jpg">
  <p>Promotional banner</p>
</block>
<block name="core/group" blockEditingMode="default">
  <h2>Customizable Section</h2>
</block>
```

## Site Editor templates from files

Add `template.json` and a template to `templates/`, or `part.json` to `parts/`, and your block theme gets file-backed `wp_template` and `wp_template_part` sources.

They use the same syntax as pages. A Site Editor customization still wins until someone resets it, and then the file source returns.

[Site templates](https://blockstudio.dev/docs/pages-and-patterns/site-templates/)

templates/front-page/index.php

```
<block name="core/template-part" slug="header" />

<div>
  <h1>Welcome</h1>
  <block name="core/post-content" />
</div>

<block name="core/template-part" slug="footer" />
```

## Selected database content in git

`wp bs content pull` projects allowlisted posts, terms, relationships, and declared metadata to portable files, and `push` applies them to another environment. Declared references, parents, and term relationships travel as stable UIDs.

Posts managed by page sync can join with `includePageSyncManaged`. Their files carry `"bodyOwner": "page-sync"`, so Content Sync moves the metadata while page sync keeps the body.

[Content Sync](https://blockstudio.dev/docs/content-sync/)

blockstudio.json

```
{
  "content": {
    "enabled": true,
    "id": "default",
    "path": "content",
    "postTypes": ["team_member"],
    "taxonomies": ["category"],
    "meta": {
      "include": ["_my_*"],
      "references": {
        "_thumbnail_id": { "kind": "attachment" },
        "_related_posts": { "kind": "post", "path": "*" }
      }
    },
    "media": "manifest"
  }
}
```

## Keyed blocks

Keep user content while templates evolve.

## Editing modes

Set page defaults and override individual elements.

## Block Bindings

Connect blocks to post meta so content survives sync.

## Post type templates

templateFor makes a page the starting block structure of every new post of a type.

## Pinned post IDs

postId reclaims the same ID when a page is deleted and synced again, so menus and links keep working.

## Scaffolds and locks

sync: false with Pages::force_sync() creates a page once for editors to own. Pages::lock() and unlock() hold one page back from syncing.

## Custom parser renderers

Builder and renderer filters turn a block tag into the block array of a third-party block or change how a core block is written.

## Element mapping

Map an HTML element to another block, pick the block from the element’s attributes, and route paragraph HTML into a content field.

## Custom discovery paths

Filters add roots for pages, patterns, and Site Editor templates, for example from a plugin.

## Logical discovery sources

Previews, overlays, and generated themes can hand Blockstudio a composed file inventory instead of one theme folder.

## Stable references

Declared post, term, and attachment references become portable UIDs on pull and resolve to local IDs on push.

## Status before push

wp bs content status reports each entity as unchanged, would-update, missing-db, conflict, locked, or orphaned, and warns about meta keys that look like secrets.

## Validated, scoped pushes

Push validates the whole plan before it writes and skips locked entities. –dry-run shows the plan, and –prune –yes removes only this content set’s entities.

## Version controlled

Track page files in Git and deploy them across environments.

## PHP API

Access trees, children, metadata, sync, locking, and IDs programmatically.

Plus

## The official extension kit

Premium site templates, AI system instructions, and a private Discord community. One-time purchase, lifetime updates.

- 500+ site templates
- AI system instructions
- Lifetime updates
- Private Discord community

[Get Plus](https://blockstudio.dev/plus/)
