From ed545bb7435e3e6bffeab6fbbb365c2ebd16ef08 Mon Sep 17 00:00:00 2001 From: Felipe Paul Martins Date: Tue, 18 Aug 2026 11:08:52 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20docs(blocks):=20document=20that?= =?UTF-8?q?=20removing=20a=20block=20breaks=20published=20content?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `create-block.md` explains every step needed to register a block, but never says that registration is what keeps *already-published* content renderable. That makes a registration look like scaffolding for new content — something safe to tidy away during an unrelated refactor. It isn't. Dropping a slug from `blocksList` makes the frontend render nothing and log "The following block does not exist: ", and dropping the WordPress-side registration makes Gutenberg treat the saved markup as invalid content. Because the slug is the link between saved content and code, a rename is a removal plus an addition. - Add a "Removing or renaming a block" section to the guide. - Add a matching rule to the wordpress-block-change skill, next to the existing "no duplicate registrations" rule, so coding agents get the same constraint. No behaviour change — documentation only. --- .claude/skills/wordpress-block-change/SKILL.md | 10 +++++++--- docs/blocks/create-block.md | 17 +++++++++++++++++ 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/.claude/skills/wordpress-block-change/SKILL.md b/.claude/skills/wordpress-block-change/SKILL.md index d5ed97b..1269dcb 100644 --- a/.claude/skills/wordpress-block-change/SKILL.md +++ b/.claude/skills/wordpress-block-change/SKILL.md @@ -32,9 +32,13 @@ Deliver block-related changes with minimal scope, no duplication, and full compa 1. Keep edits minimal and focused to requested block behavior only. 2. Do not introduce duplicate block registrations or duplicate data mappers. -3. Preserve existing naming conventions and folder structure. -4. Do not add/remove code comments unless explicitly requested. -5. If a change impacts both WP and Next, update both sides in the same task. +3. Never remove or rename an existing block registration unless that is the + explicit request. Registration is what keeps already-published content + renderable — dropping it breaks live pages, not just new ones. See + [Removing or renaming a block](../../../docs/blocks/create-block.md#removing-or-renaming-a-block). +4. Preserve existing naming conventions and folder structure. +5. Do not add/remove code comments unless explicitly requested. +6. If a change impacts both WP and Next, update both sides in the same task. ## Safety Rules diff --git a/docs/blocks/create-block.md b/docs/blocks/create-block.md index abf580a..f0adadd 100644 --- a/docs/blocks/create-block.md +++ b/docs/blocks/create-block.md @@ -194,6 +194,23 @@ cd next && npx tsc --noEmit To tweak an existing core block (e.g. limit heading levels, restrict post types), add an `edit.tsx` filter under `next/src/components/core//` and export it from [`next/src/components/filters.ts`](../../next/src/components/filters.ts). This is different from registering a new custom block — see [`Heading/README.md`](../../next/src/components/core/Heading/README.md). +## Removing or renaming a block + +Registration is not just wiring for new content — it is what keeps **already-published** content renderable. Removing a block's registration, or renaming its slug, breaks every page that already uses it: + +- **Drop the slug from `blocksList`** in [`next/src/components/global/Blocks.tsx`](../../next/src/components/global/Blocks.tsx) and the frontend renders nothing for that block, logging `The following block does not exist: `. +- **Drop the WordPress-side registration** and Gutenberg no longer recognises the saved markup, so the editor shows the block as invalid content. + +Because the slug is the link between saved content and code, a rename is a removal plus an addition — old content still references the old slug. + +So: + +- Never remove or rename a registered block as a side effect of another change. Treat it as a deliberate decision that needs a content migration, not a cleanup. +- Adding a block is safe; removing one is not. +- If a block really must go, migrate or remove the content that uses it first. + +This applies to humans and coding agents alike. + ## Checklist — custom block | Step | Location |