fix: treat non-http url protocols as external links

[claude]

Requested by Elliot Hesp · Slack thread

Fixes #454

Summary

Non-http URL schemes were treated as relative doc paths instead of external links.

Before: A mailto:[email protected] link (or tel:, sms:, skype:, geo:, file:, etc.) was rendered through NextLink, which prepended the current doc path. Clicking it navigated to something like https://docs.page/owner/repo/mailto:[email protected], which 404s. The mail client never opened.

After: The same link is recognised as external and rendered as a bare anchor, so the browser hands it off to the right handler — a mailto: link opens the mail client, tel: starts a call, etc.

How: isExternalLink in app/src/lib/docs-links.ts keeps its existing http:// / https:// / // checks and additionally matches an RFC-3986 URI scheme prefix via /^[a-z][a-z0-9+.-]*:/i. Internal doc hrefs are path-like (/foo, foo/bar, #anchor, ?query) and never start with a scheme, so there are no false positives. This is future-proof and covers every scheme without enumerating them. app/src/components/doc-link.tsx now renders non-http external links as a plain <a href> without target="_blank"/rel="noopener", which only make sense for http(s) navigation.

Scope

• app/ (hosted site, MCP, Ask AI)
• packages/cli/
• packages/mdx-bundler/
• docs/ (product documentation)
• Repo / CI / other

Type of change

• Bug fix
• New feature
• Documentation
• Refactor / chore

Test plan

• bun test app/src/lib/docs-links.test.ts → 3 pass / 0 fail

• bun test app/src/lib/ → 32 pass / 0 fail (no regressions)

• bunx @biomejs/biome check on changed files → clean

• bunx tsc --noEmit -p app/tsconfig.json → no errors in changed files (only pre-existing image-asset module imports remain)

• bun run check passes locally (changed files)

• Tested locally (bun dev, CLI command, or other relevant command)

• Updated docs/ (if user-facing)

• Verified on a docs.page URL or local preview (if rendering/routing changed)

Preview check once the Railway deploy is up: open a doc containing a mailto:/tel: link on docspage-docspage-pr-<N>.up.railway.app at a path like /invertase/docs.page/<somepath> and confirm the link opens the mail client / dialer instead of 404ing.

Notes for reviewers

Added app/src/lib/docs-links.test.ts (bun:test, matching sibling docs-nav.test.ts). No other callers of isExternalLink were changed — the new behaviour is strictly more correct for all of them (scheme links are external everywhere). The doc-link.tsx change is a minimal branch split; http(s) links still open in a new tab as before.

🤖 Generated with Claude Code

https://claude.ai/code/session_01891AY181bEZxpW4iwXuMTp

---

Generated by Claude Code