Skip to content

📚 docs(blocks): document that removing a block breaks published content #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kuuak wants to merge 1 commit into
base: future
Choose a base branch
from
+24 −3
Open

📚 docs(blocks): document that removing a block breaks published content #143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions .claude/skills/wordpress-block-change/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
17 changes: 17 additions & 0 deletions docs/blocks/create-block.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<Block>/` 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: <slug>`.
- **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 |
Expand Down