Fix docs routing findings from Ahrefs audit

[lawrencecchen]

Fixes actionable internal-link and hreflang findings from the cmux Ahrefs crawl.

• place /docs/base under the shared docs layout so it exposes navigation and participates in docs search
• stop global locale Link headers from advertising unsupported /docs/base variants that return 404
• link the homepage directly to /docs/getting-started instead of the /docs redirect

Validation:

• bun test tests/seo.test.ts
• bun run typecheck
• focused ESLint, 0 errors
• bun run build, 1,989 pages generated and 427 docs indexed
• local responses: /docs/base 200 with 64 links and no hreflang header; /de/docs/base 404; homepage has no direct /docs link

Audit: https://app.ahrefs.com/site-audit/9589643/issues?current=11-07-2026T100524

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

---

Note

Low Risk
SEO and URL middleware changes with test coverage; no auth, payments, or data-layer impact.

Overview
Addresses Ahrefs audit issues around docs URLs and hreflang by tightening locale handling for English-only pages and fixing a homepage internal link.

Routing & SEO: alternateLinks: false in next-intl routing stops middleware from emitting global Link headers that pointed crawlers at localized /docs/base URLs that 404. Middleware now 301-redirects /{locale}/docs/base (non-en) to unprefixed /docs/base and rewrites /docs/base to /en/docs/base, mirroring the existing remote-tmux pattern so Accept-Language cannot land users on unsupported variants.

Homepage: Bottom “Read the docs” CTA now targets /docs/getting-started instead of /docs (redirect).

Tests: SEO middleware tests assert no global Link header on partially localized doc routes and correct redirect/rewrite behavior for Base docs. The Base docs page only updates import paths to @/ aliases in this diff.

^{Reviewed by Cursor Bugbot for commit dcaac94. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Summary by cubic

Fixes Ahrefs SEO audit by canonicalizing the English-only Base docs and disabling sitewide hreflang headers to stop advertising unsupported localized URLs. The homepage now links directly to /docs/getting-started.

• Bug Fixes
  • Canonicalized Base docs routing: 301 /[locale]/docs/base to /docs/base and rewrite /docs/base to /en/docs/base; page uses the shared docs layout.
  • Disabled global hreflang Link headers with alternateLinks: false so unsupported locale variants aren’t advertised sitewide.
  • Strengthened tests: middleware coverage for alternate-link suppression and Base docs canonicalization.

^{Written for commit dcaac94. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Updated the landing page’s “Read the docs” link to open the Getting Started documentation.

• Bug Fixes

  • Prevented invalid alternate-language links from being advertised for partially localized documentation pages.
  • Ensured /docs/base has consistent canonical/locale behavior (redirecting localized requests to the correct English route and avoiding incorrect SEO headers).

• Tests

  • Added coverage for /docs/base responses, including redirect/rewrite behavior and the absence of invalid alternate-link headers.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cmux	Ready	Preview, Comment	Jul 11, 2026 12:42pm
cmux-staging	Building	Preview, Comment	Jul 11, 2026 12:42pm

[coderabbitai]

📝 Walkthrough

Walkthrough

Localized routing disables global alternate-link headers and enforces English-only handling for base docs. SEO tests cover canonical redirects, rewrites, and headers; the landing page links to getting-started documentation, and base docs imports use the alias path.

Changes

Localized docs routing

Layer / File(s)	Summary
SEO routing behavior web/i18n/routing.ts, web/proxy.ts, web/tests/seo.test.ts	Routing disables alternate links, middleware redirects localized base-docs requests to /docs/base, rewrites canonical requests to /en/docs/base, and tests validate status, headers, redirects, and rewrites.
Docs navigation and imports web/app/[locale]/(landing)/page.tsx, web/app/[locale]/(landing)/docs/base/page.tsx	The landing footer links to /docs/getting-started, and the base docs page uses @/-aliased imports.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Browser
  participant Proxy
  participant BaseDocsRoute
  Browser->>Proxy: Request /docs/base or /de/docs/base
  Proxy->>Proxy: Redirect non-English locale or rewrite canonical URL
  Proxy->>BaseDocsRoute: Route /en/docs/base
  BaseDocsRoute-->>Browser: Return docs response without link header

Loading

Possibly related PRs

• manaflow-ai/cmux#7247: Updates documentation middleware with related locale-based routing and alternate-link behavior.

🚥 Pre-merge checks | ✅ 24 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (24 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Cmux Swift Actor Isolation	✅ Passed	PASS — The PR diff only touches web/proxy.ts; no Swift files or actor-isolation-affecting Swift changes are present.
Cmux Swift Blocking Runtime	✅ Passed	PR changes only web/TypeScript files; no Swift files were added or modified, so the blocking-runtime rule is not implicated.
Cmux Browser Automation Off-Main	✅ Passed	PR only changes web/proxy.ts for docs routing; no browser.* commands, socket-worker routing, or WebKit/AppKit policy files are touched.
Cmux Expensive Synchronous Load	✅ Passed	PASS: The PR only changes web/proxy.ts; no Swift files or main-actor/agent-history load paths are touched, so the Swift-specific check is not applicable.
Cmux Cache Substitution Correctness	✅ Passed	Diff only adds locale canonicalization redirects/tests; no fresh read was swapped for a cache in any persistence/history/snapshot path.
Cmux No Hacky Sleeps	✅ Passed	Diff only updates routing in web/proxy.ts; no sleeps, timers, polling loops, or wall-clock delays were added.
Cmux Algorithmic Complexity	✅ Passed	Only fixed-path middleware branches and a tiny 3-item Set were added; no nested scans or rescans over scalable collections.
Cmux Swift Concurrency	✅ Passed	PASS: The PR diff only changes web/proxy.ts; no Swift files or Swift concurrency patterns are introduced, so the check is not applicable.
Cmux Swift @Concurrent	✅ Passed	PASS: The PR only touches web TS/TSX files; no Swift files or Swift concurrency annotations are changed, so the Swift-specific rule doesn’t apply.
Cmux Swift File And Package Boundaries	✅ Passed	This PR only changes web TypeScript files; no Swift files or package boundaries are touched, so the Swift boundary rule is not applicable.
Cmux Swiftpm Lockfiles	✅ Passed	PR only changes web app routing/SEO files; no Package.swift, Package.resolved, Xcode, .gitignore, or workflow dependency files changed.
Cmux Swift Logging	✅ Passed	No Swift files or runtime Swift logging changes are in the diff; only web/proxy.ts changed.
Cmux User-Facing Error Privacy	✅ Passed	Diff only changes routing, links, tests, and docs; no user-facing error/alert/API/recovery copy exposing sensitive implementation details.
Cmux Full Internationalization	✅ Passed	No new user-facing copy was added; existing docs and homepage text stay localized, and the routing/message catalogs remain aligned with the supported locales.
Cmux Swiftui State Layout	✅ Passed	No Swift/SwiftUI files changed in the PR diff, so the SwiftUI state-layout rule is not applicable.
Cmux Architecture Rethink	✅ Passed	The PR only changes TypeScript web routing (web/proxy.ts); no Swift files or Swift architectural patterns are involved.
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	No Swift files changed in this PR, so the auxiliary-window close-shortcuts rule is not applicable.
Cmux Source Artifacts	✅ Passed	All changed paths are hand-written source/test/config files; no logs, caches, build output, temp dirs, or other source artifacts appear in the diff.
Cmux No Test Or Debug Seam In Production Source	✅ Passed	PR diff touches only web TypeScript files; no production Swift Sources/ files were changed.
Cmux No Ambient Global State	✅ Passed	Only web/proxy.ts changed; no Swift files or new ambient global state were introduced, so the Swift-specific rule is not applicable.
Title check	✅ Passed	The title accurately summarizes the main change: fixing docs routing issues from the Ahrefs audit.
Description check	✅ Passed	The description covers the summary and validation well; only the demo video, review trigger block, and checklist sections are missing.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-seo-routing-audit

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR corrects routing and alternate-language metadata for the docs. The main changes are:

• Moves /docs/base under the shared docs layout.
• Canonicalizes localized Base docs URLs to the English route.
• Disables global alternate-link headers in favor of route-level metadata.
• Links the homepage directly to /docs/getting-started.
• Adds focused middleware tests for the updated routing.

Confidence Score: 5/5

This looks safe to merge.

• The updated routing keeps /docs/base on its canonical English URL.
• Route-level metadata preserves the intended locale restrictions.
• The changed import paths match the repository's configured alias pattern.
• No blocking issues were found in the updated code.

Important Files Changed

Filename	Overview
web/app/[locale]/(landing)/docs/base/page.tsx	Moves the Base docs page into the shared docs layout while preserving its English-only metadata.
web/app/[locale]/(landing)/page.tsx	Updates the homepage docs link to target the Getting Started page directly.
web/i18n/routing.ts	Disables global alternate-link headers so page metadata can define supported locales.
web/proxy.ts	Adds canonical redirect and rewrite handling for the English-only Base docs route.
web/tests/seo.test.ts	Adds tests for Base docs canonical routing and suppression of global alternate-link headers.

_{Reviews (3): Last reviewed commit: "Strengthen alternate-link middleware cov..." | Re-trigger Greptile}