Custom blocks in markdown
By Steven Van ·
Existing definitions can be placed and unchanged instances preserved during page edits, while definition creation remains in private alpha.
Custom block instances with inherited bindings now appear as definition references when read through Notion’s markdown content API and Notion MCP. Previously, they appeared as unknown blocks and were included in unknown_block_ids. Readback returns the definition reference, not the rendered contents; instances with binding overrides still appear as unknown.
Place existing definitions
To place an instance, add <custom-block definition-id="UUID" /> on its own line. The instance inherits the definition’s bindings. New placements and changes to an instance’s definition require a live, readable definition in the destination workspace, with no separate workspace enablement required. Definition creation remains in private alpha.
Preserve instances during edits
An unchanged instance can survive update_content or replace_content even if the connection cannot read its definition or the definition has been deleted. Adding another instance or changing its definition still requires authorization.
The custom blocks documentation also notes that public requests reject definition-key, which is reserved for App deployments.