Edit blocks with the AI assistant

Change an existing Block, such as a shared nav or footer, by asking the assistant. The built-in assistant in ConvertSite and a connected AI tool through the ConvertSite MCP use the same Read, Write, and Edit tools, so the same request works either way. On a page a block appears only as a <block-instance> placeholder, so the assistant reads the block itself to see and change what is inside it.

Find the block and read its content

Ask the assistant which blocks you can edit, or name one in your request: "Show me what's inside the Footer block." You get back a list of the editable blocks, each with its name, its id, and its scope: this app only, or shared across the workspace. Only blocks that are actually used by a block instance on one of the app's pages are editable; built-in blocks are not.

What the assistant reads back is the block's full content: its structure, its actions, its data sources, and its variables. If the block is large, the assistant can also read just one component inside it instead of the whole block.

Make a small change with Edit

Use Edit for a targeted change to one spot in a block, such as swapping a link target or rewording a label. The assistant supplies the block id and the current XML itself, so you only need to describe the change.

1. Open the assistant in your ConvertSite project, or use a connected Claude or Codex session. If the connection is not set up yet, see Connect ConvertSite MCP to Claude. Codex setup is in Connect ConvertSite MCP to Codex.

2. Describe the change and name the block. For example: "In the Header nav block, change the Pricing link to /new-pricing."

3. Let the assistant read the block, make the change, and confirm the result with you.

The change must match one exact spot in the block's XML, so the assistant includes enough surrounding content to make the match unique. If two places could match, name the location more precisely in your request. Three rules bound every Edit on a block:

• No page is needed. Edit ignores the page setting when it targets a block.

• The block's id never changes. An edit that alters it is refused: "This edit changes the block's id. Leave the id alone."

• One target per request: a block or a table, never both in the same Edit.

Replace a whole block with Write

Use Write for a bigger rebuild, such as restructuring a footer. Write accepts a complete <block id="..."> document and replaces the existing block's content with it. It cannot create blocks this way, only replace a block that already exists; create and add blocks in the Blocks panel as described in Create and reuse Blocks.

1. Describe the block you want. For example: "Rebuild the Footer block with three columns, Company, Products, and Support, each with its own list of links."

2. Have the assistant read the block first with Read, then send the modified <block> document back with Write. If it offers to write from memory, ask it to read the current block first.

Confirm changes to a shared block

Every block is either this app only or shared across the workspace. A change to a shared block applies to every app that uses it, and restoring an app version will not undo it. For that reason the assistant refuses the change on the first try and changes nothing: it tells you the block "is shared across the workspace: this change would apply to every app that uses it, and restoring an app version will not undo it," and asks you to confirm.

Once you confirm, the assistant repeats the same request with confirmation turned on, and the change applies to the block everywhere it is used.

What the assistant refuses

A refused write or edit is rejected in full and nothing is applied. The assistant declines when:

• The block is built-in. Built-in blocks cannot be edited through the assistant.

• No block with that id is used on the app's pages. Name the block instead; the assistant finds its id itself.

• The change would swap the block's root element, for example turning a <section> into something else. Change what is inside the root instead.

• The result is identical to the current block. Defaults are omitted from the XML, so setting a property to its default value is a no-op: "No change was applied: the resulting block is identical to the current one."

• The block would contain an instance of itself, directly or through another block.

• A block nested inside would use a block the app cannot access, or a built-in block.

• A table datasource points at a table that does not exist or is not available to the app. Create the table first, or have the assistant find the right table id with Read.

• A component, action, variable, or datasource id is already used on another page or block in the app. Ids must be unique across the app.

• A shared block would be newly bound to a table that belongs to one app only. Bind a workspace table instead.

Tables work the same way: to change a table's rows instead of a block, see Edit table rows with the AI assistant.