Skip to content

fix: repair dead-URL redirects and add 301s for removed doc versions - #2072

Merged
Yilialinn merged 2 commits into
masterfrom
fix/dead-url-redirects
Jul 13, 2026
Merged

fix: repair dead-URL redirects and add 301s for removed doc versions#2072
Yilialinn merged 2 commits into
masterfrom
fix/dead-url-redirects

Conversation

@moonming

Copy link
Copy Markdown
Member

Problem

Matomo (Apache Analytics, site 17) recorded 11,401 Page-Not-Found visits in 2026-06-14..07-11 (+485% vs the prior period). Probing every URL in the top-120 404 inventory against the live site shows 92 are still broken today, in four classes:

  1. Self-inflicted: the version-less ingress-controller rules in .htaccess still redirect to 1.8.0/... — but 1.8.0 is no longer built (only the newest release is published since chore(website): clean up doc/blog workspaces + open homepage links in new tab #2066-era pruning), so our own redirects generate 404s. They even hijack /docs/ingress-controller/FAQ/ and /upgrade/, which exist again as real pages in the current IA.
  2. Removed sub-project doc versions: ingress-controller 0.4.0–1.8.0, docker apisix-*/apisix-dashboard-*, apisix 2.1–2.5 — still linked from search results and external sites.
  3. Bare landing directories (/docs/apisix/, /docs/apisix/plugins/, /docs/ingress-controller/, …) return 403 (no index page) while receiving real traffic.
  4. Removed/renamed pages: the dashboard docs are gone from the site entirely; /docs/apisix/stand-alone; GitHub-style paths.

Fix

  • Retarget the stale version-less ingress rules to their closest pages in the current IA (concepts/references → api-reference, deployments → install, tutorials → per-page or overview, upgrade → upgrade-guide); delete the FAQ hijack.
  • Add version-stripping 301s for removed sub-project versions — renamed pages chain onto the retargeting rules as a second hop. The apisix project itself is excluded (3.10+ are still built; its 2.x/3.x legacy redirects are handled at the infra layer).
  • Redirect dashboard docs to /docs/apisix/dashboard/, bare landing dirs to real entry pages, plus two renamed-path fixes.

Verification (local httpd, mod_alias + this exact .htaccess)

  • 89 of 92 currently-broken URLs terminate at a live-200 page within ≤2 hops.
  • Zero redirect loops (5-hop chase on every URL).
  • /docs/ingress-controller/1.8.0/FAQ/ chains to /FAQ/, which becomes a real page once this deploys (the hijack rule is removed in the same change).
  • A 38-URL control set (all current sub-project pages from the sitemap + apisix latest/versioned/next docs + hub pages) passes through with no redirect — no false positives.
  • Intentionally not covered: /v2 (95 hits, ambiguous intent — no defensible target) and one single-hit CHANGELOG.md path.

Follows up on #2070 (versioned-docs canonical); together these address the two P0 technical-SEO items from the GSC/Matomo analysis.

moonming added 2 commits July 13, 2026 15:11
Sourced from the Matomo 404 inventory (2026-06-14..07-11, 11,401
Page-Not-Found visits) with every URL re-verified against the live site:

- Retarget the version-less ingress-controller rules that still pointed
  at 1.8.0 — those pages are no longer built, so the rules themselves
  were generating 404s (incl. hijacking the real /FAQ/ and /upgrade/
  pages that exist again in the 2.x IA).
- Strip the version segment from removed sub-project doc versions
  (ingress-controller 0.x/1.x, docker apisix-*/apisix-dashboard-*,
  apisix 2.1-2.5); renamed pages chain onto the retargeting rules.
- Redirect removed dashboard docs to /docs/apisix/dashboard/.
- Send bare landing directories that 403 (no index) to real entry pages.
- Fix /docs/apisix/stand-alone and a GitHub-style path.

Verified with a local httpd (mod_alias + this .htaccess): 89 of 92
currently-broken URLs now terminate at a live 200 page within 2 hops,
zero redirect loops, and a 38-URL control set of live pages passes
through untouched.
/docs/apisix/how-to-build/ and /docs/apisix/architecture-design/plugin-config/
are themselves 404 in the current IA; the new version-stripping rules were
routing fresh traffic into them. Point install -> building-apisix/ and the
plugin rules -> terminology/plugin-config/ (en+zh), let bare removed
ingress version dirs chain to overview via (.*), and fix a comment that
implied mod_alias rule order matters across hops.

Re-verified with local httpd: audit-flagged chains now 200 in <=2 hops;
full 92-URL suite and 32-URL control set unchanged (0 loops, 0 hijacks).
@moonming

Copy link
Copy Markdown
Member Author

Independent audit verdict: MERGE (0 HIGH). The one MEDIUM — the new strip rules funneled traffic into four pre-existing redirects whose targets (/docs/apisix/how-to-build/, /docs/apisix/architecture-design/plugin-config/) are themselves 404 — is addressed in bc20491: retargeted to building-apisix/ and terminology/plugin-config/ (en+zh, all four verified 200), bare removed ingress version dirs now chain to overview via (.*), and the misleading ordering comment is fixed. Local-httpd regression re-run after the amend: 92-URL suite terminates at live-200 in ≤2 hops, 0 loops, control set untouched.

@Yilialinn
Yilialinn merged commit 0b0d4b3 into master Jul 13, 2026
4 checks passed
@Yilialinn
Yilialinn deleted the fix/dead-url-redirects branch July 13, 2026 07:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants