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
mixpanel-docs	🟢 Ready	View Preview	Sep 30, 2026, 11:11 PM

[greptile-apps]

Confidence Score: 4/5

[Low risk] Updates internal documentation links to match reorganized page structure.

The PR is not ready to merge until the Agent Intelligence setup example reliably produces spans with the required user identifier.

_{Reviews (28) · Last reviewed commit: "Merge origin/main into copilot/tof-441-f..."}

[tylergoerzen-mxp]

@mbocianski conflicts are resolved: merged main and pushed two commits so you can review them separately.

8298f05: merge only. Took main's side in all 4 content conflicts, because each points at a more specific live page than the generic onboarding-playbook fallback (product-analytics-strategy/get-started, developer-environments, guides-by-topic/govern-data). docs.json kept main's new AI-guide redirects.

bc49444: re-flatten after the merge. Main's AI-guides reorg (#182) added redirects and new links, so the PR's zeros stopped holding:

• 13 residual chains the first pass missed (/docs/ trailing slash, ?sdk=httpapi query) plus 3 dangling destinations already on main
• ~50 links repointed to /guides/mcp, /guides/mixpanel-agent, /guides/use-mixpanel-ai
• stale anchors fixed against real headings (onboarding-playbook/plan/tracking-strategy#…, use-cases#rca-agent / #experiments-agent, lookup-tables -- typo, pricing group-keys)

PR #180's check_redirects.py and check_links.py both pass on the merged tree (882 rules; main added 9).

Left alone on purpose: /changelogs/<slug> links that hit the /changelogs/* catch-all (fixing them means guessing anchors), and a #group-keys-tracked-as-event-properties anchor that's broken on 14 SDK pages on main that this PR doesn't touch.

[tylergoerzen-mxp]

@mbocianski this is current with main again and ready for another look. Because main moved and I pushed new commits, it needs a fresh approval on the latest push (cd07c295) before it can merge.

What changed since your review

• e215fafe: merged main (3 commits: GDPR/CCPA export docs, end-user-data-management edit, audit-logs publish). No conflicts.
• cd07c295: small cleanups on top of your edits. Your edits are otherwise untouched.
  • Dropped the stray ? in install-mixpanel?#javascript, ?#python, ?#react-native, ?#ios-swift
  • amazon-s3.mdx pointed "Mixpanel format" at mixpanel.com/docs/... (wrong host); google-cloud-storage.mdx used an absolute docs.mixpanel.com URL. Both are now /docs/data-structure/concepts.
  • "Mixpanel's uses a SCIM spec subset" → "Mixpanel uses a SCIM spec subset"

I checked your tab anchors (#javascript, #ios-objective-c, #unity, etc.) against the rendered page. They all match Mintlify's tab ids.

Re-verified on the merged tree (script checks exact and wildcard sources, ignoring #fragment, ?query, and trailing slash)

Check	main	This PR
Redirect chains	251	0
Redirect loops	0	0
Duplicate sources	0	0
Dangling redirect destinations	2	0
Content links to a redirect source	177	7
Content links to a missing page	0	0
New broken anchors vs. main	n/a	0

• All 882 redirect sources are unchanged and in the same order. Only destinations moved.
• The 7 remaining links are /changelogs/<slug> links caught by the /changelogs/* catch-all, left alone as noted earlier.
• The Warehouse Sync Monitoring redirect from Remove Warehouse Sync Monitoring docs page and add redirect #251 lands directly on data-volume-monitoring, so no new chain.

One question for you: sdks/ios.mdx is the deprecated Objective-C SDK page, but its quickstart link now goes to #ios-swift. Was that intentional, to push people to Swift? If not, #ios-objective-c is the matching tab.

[tylergoerzen-mxp]

@mbocianski I merged main again after #173, #175, and #177 landed. This needs a fresh approval on 34486ca2.

• d845fdb9 is the merge. warehouse-connectors.mdx keeps this PR's links and your wording, using main's straight quotes. faqs.mdx takes main's new stub.
• 34486ca2: the FAQ split moved 3 links this PR had already fixed into the new per-topic pages, where they pointed at redirect sources again. They're repointed now (building-reports, identity-management, managing-projects).

Check	main	This PR
Redirect chains	251	0
Redirect loops	0	0
Duplicate sources	0	0
Dangling redirect destinations	2	0
Content links to a redirect source	177	7 (all /changelogs/<slug> catch-all, unchanged)
Content links to a missing page	1	1 (intentional /docs/quickstart.md example on the new Docs for AI Agents page)
New broken anchors vs. main	n/a	0

The new merges added no redirect chains. The redirect count is still 882.

[mbocianski]

@tylergoerzen-mxp just need an approval with write access. Looks good. Changed that one link to objective C as you mentoned.