Skip to content

The only tool you need to know what is happening and how to fix it.

feat: docs page formatting and coloring

ddux1c0f82debc0f
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 76735534..124b2b60 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -5,8 +5,11 @@
- The header navbar items must always be aligned to the left (next to the logo), not centered or spread across the header. This is achieved via CSS in `styles/custom.css`.
- Navbar order: Docs, Learn, Protocol, Self Host (controlled by key order in `pages/_meta.json`).
-## SDK Query Parameter
-
-- The `sdk` query parameter (e.g., `?sdk=go-gin`) must be sticky across all `/client` pages. When a user selects a framework, every sidebar link click and page navigation within `/client` must preserve the `sdk` param in the URL.
-- This is handled by the `SdkProvider` in `components/SdkContext.jsx` which listens to route changes and re-injects the `sdk` param if missing.
-- All internal links within `/client` pages should propagate `sdk` — do not create links that would drop the parameter.
+## SDK Selection (path-derived)
+
+- The URL **path is the single source of truth** for the active SDK. There is **no `?sdk=` query parameter** — do not reintroduce one, and never append `?sdk=` to internal `/client` links.
+- `resolveSdkFromPath(pathname, lastSdk)` in `components/SdkContext.jsx` maps the first path segment after `/client/` to an SDK via `FOLDER_SDK`. Folders that map 1:1 to a framework (e.g. `gin-middleware` → `go-gin`, `react` → `js-react`) are authoritative.
+- Two folders are shared/ambiguous (`SHARED_FOLDERS`): `sdk` (Go SDK Reference, any `go-*`) and `js-sdk` (JS SDK Reference, the JS frontend group). These disambiguate via the remembered framework in `localStorage['traceway-docs-sdk']` (`lastSdk`) when it belongs to the folder's group, otherwise fall back to `go-generic` / `js-generic`.
+- `localStorage` stores only `lastSdk`. It is written when a specific SDK is resolved from the path, or when the user picks a framework from the dropdown (`SdkSelector`) or the `/client` picker (`FrameworkPicker`).
+- Sidebar item visibility (`SDK_VISIBILITY` in `theme.config.jsx`) and the dropdown label both derive from the path-resolved SDK. `SDK_VISIBILITY` must stay complete (every `/client/<folder>` needs an entry) and matching is by exact first path segment, not substring.
+- Stray `?sdk=` params on `/client` URLs are self-healed: `SdkProvider` strips them via a shallow `router.replace`, so old bookmarks/links correct themselves.
diff --git a/docs/components/FrameworkPicker.jsx b/docs/components/FrameworkPicker.jsx
index ac00bb43..d1795780 100644
--- a/docs/components/FrameworkPicker.jsx
+++ b/docs/components/FrameworkPicker.jsx
@@ -208,7 +208,7 @@ export default function FrameworkPicker() {
function handleSelect(fw) {
setSdk(fw.value);
- router.push(`${fw.href}?sdk=${fw.value}`);
+ router.push(fw.href);
}
return (
diff --git a/docs/components/SdkContext.jsx b/docs/components/SdkContext.jsx
index 69acc0fb..da6ef43d 100644
--- a/docs/components/SdkContext.jsx
+++ b/docs/components/SdkContext.jsx
@@ -31,10 +31,9 @@ export const SDK_OPTIONS = [
const STORAGE_KEY = 'traceway-docs-sdk'
const VALID_VALUES = new Set(SDK_OPTIONS.map((o) => o.value))
-// IMPORTANT: longer/more-specific path segments must come before any shorter
-// substring that would otherwise match first. `react-native` must precede
-// `react`, otherwise `/client/react-native` would match `/react` first.
-const PATH_SDK_MAP = {
+// First path segment after /client/ → exact SDK value. These folders map 1:1
+// to a single framework, so the path alone is authoritative.
+const FOLDER_SDK = {
'gin-middleware': 'go-gin',
'chi-middleware': 'go-chi',
'fiber-middleware': 'go-fiber',
@@ -43,15 +42,15 @@ const PATH_SDK_MAP = {
'node-sdk': 'js-node',
'nestjs': 'js-nestjs',
'hono': 'js-hono',
- 'react-native': 'react-native',
+ 'nextjs': 'js-nextjs',
'react': 'js-react',
+ 'react-native': 'react-native',
'vue': 'js-vue',
'svelte': 'js-svelte',
'jquery': 'js-jquery',
'openrouter': 'openrouter',
'otel': 'otel',
'cloudflare': 'cloudflare',
- 'nextjs': 'js-nextjs',
'symfony': 'php-symfony',
'laravel': 'php-laravel',
'django': 'python-django',
@@ -59,110 +58,75 @@ const PATH_SDK_MAP = {
'android': 'android',
}
+// Shared reference folders — the SDK cannot be derived from the path alone.
+// Disambiguated by the remembered framework (lastSdk) when it belongs to the
+// folder's group, otherwise by a generic fallback.
+const SHARED_FOLDERS = {
+ 'sdk': {
+ members: new Set(['go-gin', 'go-chi', 'go-fiber', 'go-fasthttp', 'go-http', 'go-generic']),
+ fallback: 'go-generic',
+ },
+ 'js-sdk': {
+ members: new Set(['js-react', 'js-vue', 'js-svelte', 'js-jquery', 'js-generic']),
+ fallback: 'js-generic',
+ },
+}
+
+function clientSegment(pathname) {
+ if (!pathname || !pathname.startsWith('/client')) return undefined
+ return pathname.split('/').filter(Boolean)[1]
+}
+
+// The path is the single source of truth for the active SDK. `concrete` is true
+// when the path unambiguously implies the SDK (so it should be remembered).
+export function resolveSdkFromPath(pathname, lastSdk) {
+ const seg = clientSegment(pathname)
+ if (seg === undefined) return { sdk: null, concrete: false }
+ if (FOLDER_SDK[seg]) return { sdk: FOLDER_SDK[seg], concrete: true }
+ const shared = SHARED_FOLDERS[seg]
+ if (shared) {
+ if (lastSdk && shared.members.has(lastSdk)) return { sdk: lastSdk, concrete: false }
+ return { sdk: shared.fallback, concrete: false }
+ }
+ return { sdk: null, concrete: false }
+}
+
const SdkContext = createContext({
- sdk: 'go-gin',
+ sdk: null,
setSdk: () => {},
})
export function SdkProvider({ children }) {
const router = useRouter()
- const [sdk, setSdkState] = useState('go-gin')
+ const [sdk, setSdkState] = useState(null)
useEffect(() => {
- const params = new URLSearchParams(window.location.search)
- const urlSdk = params.get('sdk')
- if (urlSdk && VALID_VALUES.has(urlSdk)) {
- setSdkState(urlSdk)
- localStorage.setItem(STORAGE_KEY, urlSdk)
- return
+ const asPath = router.asPath
+ const hashIdx = asPath.indexOf('#')
+ const hash = hashIdx >= 0 ? asPath.slice(hashIdx) : ''
+ const noHash = hashIdx >= 0 ? asPath.slice(0, hashIdx) : asPath
+ const qIdx = noHash.indexOf('?')
+ const pathname = qIdx >= 0 ? noHash.slice(0, qIdx) : noHash
+ const params = new URLSearchParams(qIdx >= 0 ? noHash.slice(qIdx + 1) : '')
+
+ const lastSdk = localStorage.getItem(STORAGE_KEY)
+ const { sdk: resolved, concrete } = resolveSdkFromPath(pathname, lastSdk)
+ if (resolved) {
+ setSdkState(resolved)
+ if (concrete && VALID_VALUES.has(resolved)) {
+ localStorage.setItem(STORAGE_KEY, resolved)
+ }
}
- const stored = localStorage.getItem(STORAGE_KEY)
- if (stored && VALID_VALUES.has(stored)) {
- setSdkState(stored)
- }
- }, [])
-
- useEffect(() => {
- const params = new URLSearchParams(window.location.search)
- const urlSdk = params.get('sdk')
- if (urlSdk && VALID_VALUES.has(urlSdk) && urlSdk !== sdk) {
- setSdkState(urlSdk)
- localStorage.setItem(STORAGE_KEY, urlSdk)
+ // Self-heal: strip any stray ?sdk= so /client URLs stay clean and old
+ // bookmarks that pinned the wrong SDK correct themselves.
+ if (pathname.startsWith('/client') && params.has('sdk')) {
+ params.delete('sdk')
+ const qs = params.toString()
+ router.replace(pathname + (qs ? '?' + qs : '') + hash, undefined, { shallow: true })
}
}, [router.asPath])
- // Keep sdk param sticky on all /client pages
- useEffect(() => {
- function handleRouteChange(url) {
- if (!url.startsWith('/client')) return
-
- const hashIdx = url.indexOf('#')
- const questionIdx = url.indexOf('?')
-
- let pathname, search, hash
- if (hashIdx === -1 && questionIdx === -1) {
- pathname = url; search = ''; hash = ''
- } else if (questionIdx !== -1 && (hashIdx === -1 || questionIdx < hashIdx)) {
- pathname = url.substring(0, questionIdx)
- const rest = url.substring(questionIdx + 1)
- const restHash = rest.indexOf('#')
- if (restHash !== -1) {
- search = rest.substring(0, restHash)
- hash = rest.substring(restHash)
- } else {
- search = rest; hash = ''
- }
- } else {
- pathname = url.substring(0, hashIdx)
- const rest = url.substring(hashIdx)
- const restQ = rest.indexOf('?')
- if (restQ !== -1) {
- hash = rest.substring(0, restQ)
- search = rest.substring(restQ + 1)
- } else {
- hash = rest; search = ''
- }
- }
-
- const params = new URLSearchParams(search)
-
- if (pathname === '/client') {
- if (params.has('sdk')) {
- params.delete('sdk')
- const qs = params.toString()
- router.replace(pathname + (qs ? '?' + qs : '') + hash, undefined, { shallow: true })
- }
- localStorage.removeItem(STORAGE_KEY)
- setSdkState('go-gin')
- return
- }
-
- if (!params.get('sdk')) {
- let detectedSdk = null
- for (const [folder, sdkValue] of Object.entries(PATH_SDK_MAP)) {
- if (pathname.includes('/' + folder)) {
- detectedSdk = sdkValue
- break
- }
- }
- const sdkToUse = detectedSdk || localStorage.getItem(STORAGE_KEY) || sdk
- if (sdkToUse && VALID_VALUES.has(sdkToUse)) {
- params.set('sdk', sdkToUse)
- if (detectedSdk) {
- setSdkState(detectedSdk)
- localStorage.setItem(STORAGE_KEY, detectedSdk)
- }
- const qs = params.toString()
- router.replace(pathname + (qs ? '?' + qs : '') + hash, undefined, { shallow: true })
- }
- }
- }
-
- router.events.on('routeChangeComplete', handleRouteChange)
- return () => router.events.off('routeChangeComplete', handleRouteChange)
- }, [router, sdk])
-
const setSdk = useCallback((value) => {
if (!VALID_VALUES.has(value)) return
setSdkState(value)
diff --git a/docs/components/SdkSelector.jsx b/docs/components/SdkSelector.jsx
index 61cec633..6e9ad377 100644
--- a/docs/components/SdkSelector.jsx
+++ b/docs/components/SdkSelector.jsx
@@ -22,6 +22,8 @@ const SDK_QUICK_START = {
'otel': '/client/otel',
'cloudflare': '/client/cloudflare',
'php-symfony': '/client/symfony',
+ 'php-laravel': '/client/laravel',
+ 'python-django': '/client/django',
'flutter': '/client/flutter',
'android': '/client/android',
'react-native': '/client/react-native',
@@ -98,7 +100,7 @@ export default function SdkSelector() {
setSearch('')
const href = SDK_QUICK_START[option.value]
if (href) {
- router.push(`${href}?sdk=${option.value}`)
+ router.push(href)
}
}}
>
diff --git a/docs/pages/client/android/index.mdx b/docs/pages/client/android/index.mdx
index 4ee05e2f..1b2cf4fe 100644
--- a/docs/pages/client/android/index.mdx
+++ b/docs/pages/client/android/index.mdx
@@ -231,4 +231,4 @@ Tap the button and check your Traceway dashboard to verify the error appears wit
|----------|----------------|------------------|
| Android (API 21+) | Yes | No |
-For Flutter apps that need cross-platform error tracking (and screen recording on iOS / Android / macOS), use the [Flutter SDK](/client/flutter?sdk=flutter) instead — it ships the same wire format so a single Traceway backend handles both.
+For Flutter apps that need cross-platform error tracking (and screen recording on iOS / Android / macOS), use the [Flutter SDK](/client/flutter) instead — it ships the same wire format so a single Traceway backend handles both.
diff --git a/docs/pages/client/flutter/index.mdx b/docs/pages/client/flutter/index.mdx
index 16d0e049..49678f67 100644
--- a/docs/pages/client/flutter/index.mdx
+++ b/docs/pages/client/flutter/index.mdx
@@ -284,7 +284,7 @@ For Flutter web, use the JS SDK instead — see [Flutter Web](#flutter-web) belo
## Flutter Web
-This SDK does not support Flutter web. For web apps, use the [`@tracewayapp/frontend`](/client/js-sdk?sdk=js-generic) JS SDK which provides rrweb session replay and automatic fetch instrumentation.
+This SDK does not support Flutter web. For web apps, use the [`@tracewayapp/frontend`](/client/js-sdk) JS SDK which provides rrweb session replay and automatic fetch instrumentation.
**Add the CDN script to `web/index.html`:**
@@ -308,4 +308,4 @@ npm install @tracewayapp/frontend
</script>
```
-See the full [JS SDK documentation](/client/js-sdk?sdk=js-generic) for all options including session recording, error filtering, and distributed tracing.
+See the full [JS SDK documentation](/client/js-sdk) for all options including session recording, error filtering, and distributed tracing.
diff --git a/docs/pages/client/react-native/index.mdx b/docs/pages/client/react-native/index.mdx
index 39ce9cb7..cb57e9da 100644
--- a/docs/pages/client/react-native/index.mdx
+++ b/docs/pages/client/react-native/index.mdx
@@ -26,7 +26,7 @@ export default function App() {
That's it. Every uncaught throw, unhandled promise rejection, render-time exception, and `fetch` call is captured automatically. If you want to replace a crashed subtree with a custom fallback view, `TracewayErrorBoundary` is still exported for that purpose.
-> **No screen recording.** Unlike the browser SDK ([`@tracewayapp/frontend`](/client/js-sdk?sdk=js-generic)), this package does not record the screen. The `rrweb` recorder is intentionally absent — nothing in the bundle reaches into a DOM that doesn't exist.
+> **No screen recording.** Unlike the browser SDK ([`@tracewayapp/frontend`](/client/js-sdk)), this package does not record the screen. The `rrweb` recorder is intentionally absent — nothing in the bundle reaches into a DOM that doesn't exist.
## Capture Errors Manually
@@ -291,4 +291,4 @@ Tap the button and check your Traceway dashboard to verify the error appears wit
| Expo (SDK 49+) | Yes — works in Expo Go | No |
| Web (via React Native Web) | Yes | No |
-For native Android-only apps without React Native, use the [Android SDK](/client/android?sdk=android). For Flutter apps, use the [Flutter SDK](/client/flutter?sdk=flutter). For browser apps, use the [React SDK](/client/react?sdk=js-react) or [generic JS SDK](/client/js-sdk?sdk=js-generic).
+For native Android-only apps without React Native, use the [Android SDK](/client/android). For Flutter apps, use the [Flutter SDK](/client/flutter). For browser apps, use the [React SDK](/client/react) or [generic JS SDK](/client/js-sdk).
diff --git a/docs/styles/custom.css b/docs/styles/custom.css
index 4035d0c5..d2d16fb0 100644
--- a/docs/styles/custom.css
+++ b/docs/styles/custom.css
@@ -288,6 +288,27 @@ main hr,
box-shadow: 0 0 0 3px color-mix(in oklab, var(--a1) 15%, transparent);
}
+/* Results panel: solid surface. Nextra's default is translucent + backdrop-blur,
+ which lets page content bleed through and makes the results unreadable. */
+.nextra-search ul.nextra-scrollbar {
+ background-color: var(--ink-2) !important;
+ -webkit-backdrop-filter: none !important;
+ backdrop-filter: none !important;
+ border-color: var(--hair-2) !important;
+}
+
+/* Matched query terms: Nextra colors these with the dark indigo primary, which
+ is hard to read on the panel — lighten so the match stands out legibly. */
+.nextra-search .nx-text-primary-600 {
+ color: color-mix(in oklab, var(--a1) 55%, var(--fg-0)) !important;
+ font-weight: 600;
+}
+
+/* Result excerpt: default gray-400 is too dim on the solid dark panel. */
+.nextra-search .excerpt {
+ color: var(--fg-1) !important;
+}
+
/* =========================================================================
Navbar alignment (pre-existing rules, preserved)
========================================================================= */
diff --git a/docs/theme.config.jsx b/docs/theme.config.jsx
index 013e4424..51631037 100644
--- a/docs/theme.config.jsx
+++ b/docs/theme.config.jsx
@@ -14,6 +14,7 @@ const SDK_VISIBILITY = {
nestjs: "js-nestjs",
hono: "js-hono",
react: "js-react",
+ "react-native": "react-native",
vue: "js-vue",
svelte: "js-svelte",
jquery: "js-jquery",
@@ -23,6 +24,8 @@ const SDK_VISIBILITY = {
cloudflare: "cloudflare",
nextjs: "js-nextjs",
symfony: "php-symfony",
+ laravel: "php-laravel",
+ django: "python-django",
flutter: "flutter",
android: "android",
};
@@ -80,10 +83,12 @@ export default {
return <SdkSelector />;
}
- for (const [folder, requiredSdk] of Object.entries(SDK_VISIBILITY)) {
- if (route && route.includes(`/${folder}`)) {
- return <SdkGuard requiredSdk={requiredSdk}>{title}</SdkGuard>;
- }
+ const segment = route?.startsWith("/client")
+ ? route.split("/").filter(Boolean)[1]
+ : undefined;
+ const requiredSdk = segment ? SDK_VISIBILITY[segment] : undefined;
+ if (requiredSdk !== undefined) {
+ return <SdkGuard requiredSdk={requiredSdk}>{title}</SdkGuard>;
}
return <>{title}</>;
@@ -102,6 +107,9 @@ export default {
function SdkGuard({ requiredSdk, children }) {
const { sdk } = useSdk();
+ if (!sdk) {
+ return <HiddenItem />;
+ }
let visible;
if (Array.isArray(requiredSdk)) {
visible = requiredSdk.includes(sdk);