Global blocks and block templates

There are two ways to reuse blocks, and they behave differently on purpose:

	Global block	Block template
What a page holds	A reference	Its own copy
Editing the source	Changes every page that uses it	Changes only future inserts
Editing on the page	Not possible; detach to get a copy	Edit freely
Use for	A call to action, an announcement, a contact strip that must match everywhere	A pricing row, a feature trio, a FAQ section you adapt per page

Both use named styles rather than raw HTML, so a reused section still follows the site’s look.

Ask an agent to set up reusable sections

A connected AI agent can inspect an existing section and turn it into a global block or save it as a block template. This is a useful way to build the reusable design without manually assembling every block. Specify whether later changes should update every use or whether each Page should have its own editable copy.

For example: “Make this contact strip a global block so its content stays the same wherever we use it. Save the feature section as a block template so editors can adapt each inserted copy. Show me the affected Pages before deployment.”

Review the result in the editor. The MCP/API reference below lists the tools; the following sections also explain how to perform the same tasks manually.

Global blocks

A global block is one shared source. Header and footer are global blocks that appear on every page automatically; other global blocks appear where a page places them.

Create: Global blocks → New global block (Blocks), or in the page editor select a section and choose Reuse → Make global block. The section moves into the global block and the page keeps a reference in its place.
Add to a page: in the block library, under Global blocks. The page stores a core/global_block block with global_block_id.
Edit: open it from Global blocks. The editor lists where it is used: pages (including page drafts), page templates, and other global blocks that contain it, including the header and footer. The Global blocks list shows the same count, for example “used on 2 pages and 1 template”. Changes reach every page while the global block is Published; the live site updates at the next deploy.
Detach: select the reference and choose Reuse → Detach. The page gets an editable copy and no longer follows the global block. The copy is what the editors show: the global block’s unsaved draft on this version when it has one, otherwise the saved global block.

A header or footer in block mode opens in the same block editor. Changes save as you edit and appear on every page while it is Published. When a global block, header or footer has an unsaved draft, for example from an agent, the editor shows the draft and asks you to Save draft or Discard draft before you edit it.

The global block renders in place, with no extra wrapper element, so spacing and full-width sections behave as if the blocks were on the page. A draft or missing global block renders nothing on the site and a warning in the editor.

Block templates

A block template is a saved section starter. Inserting one copies its blocks, with new ids, into the page; the copy is then the page’s own.

Save: in the page editor select a block and choose Reuse → Save as template, with a name and when to use it.
Insert: in the block library, under Templates. With a section or column selected, the copy goes inside it.
Manage: Global blocks → Block templates: rename or delete. Deleting a template never changes pages.

Templates belong to the site, not to a branch, so they are available in every version.

Through MCP and the API

Tool	REST	Purpose
`make_block_global`	`POST /api/v1/sites/{siteId}/pages/{pageId}/blocks/make-global`	Move a block into a new global block, keep a reference
`detach_global_block`	`POST /api/v1/sites/{siteId}/pages/{pageId}/blocks/detach`	Replace a reference with an editable copy
`create_free_block`	`POST /api/v1/sites/{siteId}/partials`	New global block from `blocks` or `html_content`
`list_block_templates`	`GET /api/v1/sites/{siteId}/block-templates`	Templates with name, description and block count
`read_block_template`	`GET /api/v1/sites/{siteId}/block-templates/{id}`	One template with its blocks
`save_block_template`	`POST /api/v1/sites/{siteId}/block-templates`	Save from `blocks` or `from: { page_id, block_id }`
`update_block_template`	`PATCH /api/v1/sites/{siteId}/block-templates/{id}`	Rename, describe or replace blocks
`delete_block_template`	`DELETE /api/v1/sites/{siteId}/block-templates/{id}`	Delete; pages keep their copies
`insert_block_template`	`POST /api/v1/sites/{siteId}/pages/{pageId}/blocks/insert-template`	Insert a copy at `parent_id`/`slot_index`/`position`

Add a reference with add_block:

add_block page_id=… block={ type: "core/global_block", data: { global_block_id: "call-to-action" } }

Edit a global block’s blocks with the block tools and target: { kind: "partial", id: "call-to-action" }. find_pages_using_block (GET /api/v1/sites/{siteId}/partials/{partialId}/usage) returns what uses it, saved or in a draft: pages, templates (page templates) and global_blocks (the header, footer and other global blocks that contain it; a header or footer means every page). Only direct references are listed; open a containing global block’s usage to follow it further. detach_global_block reports copied_from: draft or saved. Page block writes go to the page draft, like other block edits.