TOF-441: Flatten redirect chains and fix internal links to redirected URLs

[Copilot]

docs.json carried 873 redirect rules, and hundreds of them pointed at another redirect source rather than a live page. Content files also linked directly to redirect sources instead of canonical URLs.

Relates to: https://linear.app/mixpanel/issue/TOF-441/aeo-qw4-flatten-redirect-chains-and-fix-internal-links-to-redirect

Why this matters for AEO

Redirect chains are invisible to a human clicking a link and expensive for everything else.

• Google's own guidance is to redirect to the final destination and to link to canonical pages directly. Every extra hop is latency and an opportunity for a crawler to stop early.
• AI crawlers are now the majority of docs traffic — agents account for 51.8% of intentional documentation reads (GitBook, 61.2M pageviews, May 2026). They fetch far more aggressively than humans and are less forgiving of multi-hop routing.
• Internal links pointing at redirect sources dilute the canonical URL. When our own docs link to the old path, that is the URL that gets discovered and cited, even though it is not the page we want cited.

This is the least glamorous item in the plan and the most mechanically verifiable: the acceptance criterion is a number, and the number is now zero.

Result

Check	Before	After
Redirect chains	216	0
Redirect loops	0	0
Duplicate sources	0	0
Internal links pointing at a redirect source	123	0
Total rules	873	873

Rule count is deliberately unchanged. Old routes may hold external backlinks, so this flattens destinations rather than deleting anything.

Changes

• docs.json — every chained destination resolved through the graph to its final landing page, in one pass rather than per-hop
• 58 content files — 126 internal links repointed from redirect sources to canonical URLs

Corrections made during review

24 chains survived the first pass because the flattening matched on the full destination string including its #fragment, so anything with an anchor never matched its source. A second pass strips the fragment before lookup.

15 links kept an anchor that no longer exists on the new destination. These were already stale on main — the old page was deleted and the fragment rode through the redirect — but the rewrite would have hard-coded them. Each replacement was verified against the target page's actual headings. Two were landing on the wrong page entirely: /docs/reports#company-profiles and #activation-metrics both belong to group-analytics.

9 anchors were dropped rather than guessed where the heading is genuinely gone. A link to the top of the right page beats a link to a dead anchor.

17 redirect destinations pointed at onboarding-playbook subpages that do not exist. Only guides/strategic-playbooks/onboarding-playbook.mdx is real. The PR had already repointed the content links there; the map itself was still dangling.

Note on sequencing

PR #180 adds a CI gate that fails the build on new chains, loops, and duplicate sources. That gate can only be enforced once this merges. Merge this first.

[linear-code]

TOF-441

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
mixpanel-docs	🟢 Ready	View Preview	Aug 18, 2026, 7:00 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs.json	Flattens redirect destinations, including the previously reported wildcard-matching onboarding routes.
changelogs.mdx	Replaces redirected documentation links with canonical destinations.
guides/guides-by-workflow/build-tracking-strategy.mdx	Updates onboarding links to avoid wildcard redirect sources.
troubleshooting/faqs.mdx	Rewrites internal links to their final canonical pages.

_{Reviews (5): Last reviewed commit: "Merge branch 'main' into copilot/tof-441..." | Re-trigger Greptile}