task: Audit historical architecture changes and add missing redirects (Page Not Found is the #4 most-viewed page in GA4)
- Dominant language
- MDX
- Stars
- 90
- Forks
- 382
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 35
Description
## What needs to be done
Add redirects for old public URLs that still receive traffic but now **404**, and establish redirect coverage for every past architecture change (Docusaurus→Mintlify, `infra-partners/`→`operate/`, Legacy/`_deprecated` removal, MiniPay collapse, Specs fold-in, etc.).
**Evidence (GA4 — `docs.celo.org` property, Aug 3–30):** the **"Page Not Found"** page is the **#4 most-viewed page** — 74 views (4.4% of all pageviews), 33 active users (6.4%). GA4's page-*title* view can't reveal *which* paths failed, so coverage was reconstructed from git history instead.
**Audit (full `git log --all`, `origin/main` @ `2ed9dba`):**
- 2,273 historical public URLs reconstructed across both eras (confirmed Docusaurus `routeBasePath: "/"` → there is **no** `/docs/` URL prefix).
- 237 covered by a live page; 770 covered by an existing redirect.
- **1,266 currently 404 with no redirect**, broken down:
- **449** — generated GitBook/typedoc API dumps under `/developer-resources/**/reference/**`
- **415** — old Docusaurus `/blog/**`
- **107** — old `/v2/**` GitBook tree
- **295** — individual content pages (~80 with a confident target, ~215 needing an editorial target)
- Live spot-check confirmed real 404s (e.g. `/about-celo/gas-fees`, `/protocol/identity/odis`, `/developer/dev-environments/hardhat`); live controls returned 200.
## Scope / slices
1. **33 high-confidence redirects** — every destination verified to be a live page on `main`; led by `/about-celo/:slug* → /home/:slug*` (covers 26 pages). **A PR is open for this slice.**
2. **3 bulk catch-all wildcards — target decision needed (OPEN):**
- `/developer-resources/:slug*` → ? (retires 449 dead API-dump URLs)
- `/blog/:slug*` → ? (415 removed blog posts)
- `/v2/:slug*` → ? (107 old GitBook pages)
Suggested defaults: `blog` + `v2` → `/` (content retired); `developer-resources` → `/tooling/libraries-sdks/contractkit`. **OPEN (implementer/PM to confirm): pick targets, or intentionally 410/leave.**
3. **~215 individual pages with no confident target** — need editorial decisions (redirect vs intentionally retire). Largest clusters: `/protocol/**`, `/celo-codebase/protocol/**`, `/cel2/**` (Optics/Dango-era), `/bridge/optics/**`, `/developer-resources/walkthroughs/**`, `/community/celo-sage/**`.
## Definition of done
- [ ] High-confidence redirects merged (slice 1 PR)
- [ ] Bulk-bucket wildcard targets decided and added, or explicitly declined
- [ ] ~215 no-confident-target paths triaged (redirect or intentionally retire)
- [ ] `mint broken-links` passes and a re-run of the git-history audit shows 0 uncovered high-value paths
- [ ] (Ops) Confirm the "Page Not Found" pageview share drops in GA4 after deploy
- [ ] (Follow-up) Wire Google Search Console / add the `page_path` dimension to the GA4 404 view to catch future path gaps directly
## Non-goals / dependencies
- **Not** building a CI redirect-validation check — tracked separately in #1846.
- No blocking dependency; the restructure epic #2266 introduced most of the recent path changes.
## How we'd know it's fixed
- GA4 "Page Not Found" pageview share falls from ~4.4%.
- Re-running the git-history audit reports 0 missing high-value redirects.
**Priority:** high · **Size:** L (split into the 3 slices above).
_Related: #1846 (CI redirects check), #2266 (restructure epic), #2253 (orphaned-pages audit)._
Contributor guide
Assessment
This issue has not been assessed yet.