# Custom blocks in markdown By Steven Van · 2026-09-30 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. ![Notion]() Notion All-in-one workspace for notes, docs, projects, and wikis — with AI built in for writing, summarizing, and organizing. [View Notion →]() [Original source]() [Read Custom blocks in markdown on Creators Toolbox]() --- Canonical source: https://creatorstoolbox.com/blog/notion-custom-blocks-in-markdown