Redirect Playbook

Every page move requires all six steps in order. Never commit a redirect without deploying the worker.

---

The 6-step mandatory procedure

Step 1 — Add the client-redirect entry

In docusaurus.config.js, under @docusaurus/plugin-client-redirects, add:

{ from: '/old/path', to: '/new/path' },

• Use exact paths, no trailing slashes.
• from = the old URL that users/search engines have indexed.
• to = the new canonical URL.

Step 2 — Repoint any matching worker REDIRECTS targets

If the OLD path is a target of a worker redirect (i.e., REDIRECTS in redirect-worker/worker.js points to the old path), update that worker entry to point directly to the new path. This prevents a two-hop chain: old-domain → /old/path → /new/path.

// Before
"/docs/some-old-slug": "https://docs.apicontext.com/old/path",
// After
"/docs/some-old-slug": "https://docs.apicontext.com/new/path",

Step 3 — Deploy the worker

cd redirect-worker
CLOUDFLARE_API_TOKEN=$CLOUDFLARE_API_TOKEN wrangler deploy

The worker deploy is a separate action from committing. A git commit does NOT deploy to Cloudflare. The atomic redirect guarantee — no chain hops — only holds if the worker is live.

Step 4 — Run the redirect integrity check

npm run check:redirects

Fix any failures before proceeding. Common failures:

• dead target — the new page doesn't exist yet
• chain detected — worker target points to a client-redirect source
• orphan — old page removed without a redirect

Step 5 — Verify single-hop in production

curl -sI https://docs.apicontext.com/old/path | head -5

Expected: HTTP 301 → https://docs.apicontext.com/new/path (one hop, not two).

Step 6 — On step-5 failure: rollback

If the curl verify shows a chain or 404:

cd redirect-worker
wrangler rollback   # or redeploy the previous version

Then re-verify from step 4.

---

_category_.json rule

When adding a page to a sidebar section:

• If Docusaurus auto-discovers (autogenerated sidebar): simply create the .md file in the correct directory. No config change needed.
• If sidebar is hand-maintained: insert the new doc ID into the items array of the section's _category_.json. Never replace the entire file.

This prevents accidentally deleting an existing section's item list.

---

Wrangler credential check

Before any M1+ content moves, verify that CLOUDFLARE_API_TOKEN is present in CI secrets and that a dry-run passes:

cd redirect-worker
wrangler deploy --dry-run

If this fails, escalate to the infrastructure team immediately. The atomic redirect guarantee in step 3 cannot hold without deploy capability.

---

Quick reference

Step	Action	Tool
1	Add client-redirect entry	docusaurus.config.js
2	Repoint matching worker targets	redirect-worker/worker.js
3	Deploy worker	wrangler deploy
4	Run integrity check	npm run check:redirects
5	Curl verify single-hop	curl -sI
6	Rollback on failure	wrangler rollback