From 0190575ffe6d4a2a6d3e3c266d92f648d9b92f82 Mon Sep 17 00:00:00 2001
From: Maximilian Techritz <maximilian.techritz@sap.com>
Date: Wed, 22 Apr 2026 16:45:00 +0200
Subject: [PATCH] docs: add redirect requirement for ID changes to CLAUDE.md

---
 CLAUDE.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 4aa0982..b7c9bfc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -23,6 +23,28 @@ The resulting URL will be `/operators/setup` (folder path + id).
 
 Pages without an `id:` field will use the filename as-is, including any numeric prefixes — always add one when creating or renaming a page.
 
+### Avoiding breaking URLs
+
+When changing an existing `id:`, you **must** add a redirect in `docusaurus.config.ts` to preserve the old URL:
+
+```ts
+plugins: [
+  [
+    '@docusaurus/plugin-client-redirects',
+    {
+      redirects: [
+        {
+          from: '/old/path',
+          to: '/new/path',
+        },
+      ],
+    },
+  ],
+],
+```
+
+This ensures external links and bookmarks continue to work after ID changes.
+
 ## Branch workflow
 
 Work on feature branches based on `main`. Merge via PR.