From 74c3e699042c0064e1033cdb711c3703f06e67e0 Mon Sep 17 00:00:00 2001 From: Georgios Konstantopoulos Date: Fri, 16 Jan 2026 02:10:42 +0000 Subject: [PATCH 1/6] feat(docs): add custom 404 page Adds a helpful 404 page for the docs site with: - Large 404 indicator - Friendly message explaining the page wasn't found - Quick navigation cards to get back on track: - Docs Home - Get Started guide - Learn section - Search Fixes WEB-89 --- docs/pages/404.mdx | 45 ++++++++++++++++++++++++++++++++++++++++++++ docs/vercel.json | 4 ++++ docs/vocs.config.tsx | 15 ++++++++++----- 3 files changed, 59 insertions(+), 5 deletions(-) create mode 100644 docs/pages/404.mdx diff --git a/docs/pages/404.mdx b/docs/pages/404.mdx new file mode 100644 index 0000000000..04bbedbb8c --- /dev/null +++ b/docs/pages/404.mdx @@ -0,0 +1,45 @@ +--- +title: Page not found +description: The page you're looking for doesn't exist. Navigate back to Tempo documentation. +--- + +import LucideHome from '~icons/lucide/home' +import LucideBookOpen from '~icons/lucide/book-open' +import LucideRocket from '~icons/lucide/rocket' +import LucideSearch from '~icons/lucide/search' +import * as Card from "../components/Card.tsx" + +
+
404
+

Page not found

+

+ The page you're looking for doesn't exist or may have been moved. Try one of the options below to get back on track. +

+
+ + + + + + + diff --git a/docs/vercel.json b/docs/vercel.json index f4ed0bee4c..4bb0073793 100644 --- a/docs/vercel.json +++ b/docs/vercel.json @@ -9,6 +9,10 @@ "has": [{ "type": "host", "value": { "neq": "docs.tempo.xyz" } }] } ], + "routes": [ + { "handle": "filesystem" }, + { "src": "/(.*)", "status": 404, "dest": "/404" } + ], "redirects": [ { "source": "/documentation/protocol/:path*", diff --git a/docs/vocs.config.tsx b/docs/vocs.config.tsx index 383758ac3c..28164b2589 100644 --- a/docs/vocs.config.tsx +++ b/docs/vocs.config.tsx @@ -129,11 +129,16 @@ export default defineConfig({ ), ogImageUrl: { '/': 'https://docs.tempo.xyz/og-docs.png', - '/learn': 'https://docs.tempo.xyz/api/og?title=%title&description=%description', - '/quickstart': 'https://docs.tempo.xyz/api/og?title=%title&description=%description', - '/guide': 'https://docs.tempo.xyz/api/og?title=%title&description=%description', - '/protocol': 'https://docs.tempo.xyz/api/og?title=%title&description=%description', - '/sdk': 'https://docs.tempo.xyz/api/og?title=%title&description=%description', + '/learn': + 'https://docs.tempo.xyz/api/og?title=%title&description=%description', + '/quickstart': + 'https://docs.tempo.xyz/api/og?title=%title&description=%description', + '/guide': + 'https://docs.tempo.xyz/api/og?title=%title&description=%description', + '/protocol': + 'https://docs.tempo.xyz/api/og?title=%title&description=%description', + '/sdk': + 'https://docs.tempo.xyz/api/og?title=%title&description=%description', }, title: 'Tempo', titleTemplate: '%s | Tempo Docs', From ab2af71435b49c39a3c5117f5b2e7c5cdd534e1c Mon Sep 17 00:00:00 2001 From: Georgios Konstantopoulos Date: Fri, 16 Jan 2026 02:13:57 +0000 Subject: [PATCH 2/6] fix: remove routes config that conflicts with rewrites/redirects Vercel automatically serves 404.html from build output for unmatched routes --- docs/vercel.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/vercel.json b/docs/vercel.json index 4bb0073793..f4ed0bee4c 100644 --- a/docs/vercel.json +++ b/docs/vercel.json @@ -9,10 +9,6 @@ "has": [{ "type": "host", "value": { "neq": "docs.tempo.xyz" } }] } ], - "routes": [ - { "handle": "filesystem" }, - { "src": "/(.*)", "status": 404, "dest": "/404" } - ], "redirects": [ { "source": "/documentation/protocol/:path*", From 8a001b72a08bbfd93cb24e5709a0132528b9919e Mon Sep 17 00:00:00 2001 From: Georgios Konstantopoulos Date: Fri, 16 Jan 2026 02:22:22 +0000 Subject: [PATCH 3/6] fix: use catch-all route for 404 page and copy to 404.html - Rename pages/404.mdx to pages/*.mdx so Vocs treats it as catch-all route - Update build script to copy generated 404 to dist/404.html for Vercel --- docs/package.json | 2 +- docs/pages/{404.mdx => *.mdx} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/pages/{404.mdx => *.mdx} (100%) diff --git a/docs/package.json b/docs/package.json index 707b2b90f6..6fd3104538 100644 --- a/docs/package.json +++ b/docs/package.json @@ -3,7 +3,7 @@ "private": true, "type": "module", "scripts": { - "build": "NODE_OPTIONS=\"--max-old-space-size=16384\" vocs build --searchIndex", + "build": "NODE_OPTIONS=\"--max-old-space-size=16384\" vocs build --searchIndex && cp 'dist/*/index.html' dist/404.html", "check": "biome check . --write --unsafe", "check:ci": "biome check . --diagnostic-level=error", "check:types": "tsc --noEmit", diff --git a/docs/pages/404.mdx b/docs/pages/*.mdx similarity index 100% rename from docs/pages/404.mdx rename to docs/pages/*.mdx From c3428753d51692e56e75957f2c28804b9bf67061 Mon Sep 17 00:00:00 2001 From: Pierre Bertet Date: Fri, 16 Jan 2026 10:53:26 +0000 Subject: [PATCH 4/6] fix(docs): patch vocs to support custom 404 page client-side Vocs generates "/*" for *.mdx catch-all routes but checks for "*" in routes.tsx, causing client-side navigation to show the default NotFound component instead of the custom 404 page. This adds a Vite plugin to patch the route matching at build time. Co-Authored-By: Claude Opus 4.5 --- docs/vocs.config.tsx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/vocs.config.tsx b/docs/vocs.config.tsx index 28164b2589..965d089191 100644 --- a/docs/vocs.config.tsx +++ b/docs/vocs.config.tsx @@ -755,6 +755,17 @@ export default defineConfig({ }, vite: { plugins: [ + { + // Vocs generates "/*" for *.mdx but checks for "*" in routes.tsx. + // This patches the route matching to recognize both paths for 404 handling. + name: 'fix-404-route', + transform(code, id) { + if (!id.includes('vocs/_lib/app/routes')) return + return code + .replace("path === '*'", "path === '*' || path === '/*'") + .replace("path !== '*'", "path !== '*' && path !== '/*'") + }, + }, { name: 'virtual-tips', resolveId(id) { From 67c4d6ff03fa998e69dd68adc8ba992f4995501d Mon Sep 17 00:00:00 2001 From: Pierre Bertet Date: Fri, 16 Jan 2026 11:28:38 +0000 Subject: [PATCH 5/6] fix(docs): use /404 page instead of catch-all route for 404 handling - Rename *.mdx to 404.mdx so vocs builds it to dist/404/index.html - Update build script to copy from dist/404/index.html - Update vocs plugin to redirect unknown routes to /404 using Navigate The catch-all *.mdx approach didn't work because vocs doesn't prerender catch-all routes. This approach uses a regular /404 page that gets built normally, then copied to 404.html for Vercel, with client-side routing redirecting to /404. Co-Authored-By: Claude Opus 4.5 --- docs/package.json | 2 +- docs/pages/{*.mdx => 404.mdx} | 0 docs/vocs.config.tsx | 14 ++++++++++---- 3 files changed, 11 insertions(+), 5 deletions(-) rename docs/pages/{*.mdx => 404.mdx} (100%) diff --git a/docs/package.json b/docs/package.json index 6fd3104538..d32775ac4f 100644 --- a/docs/package.json +++ b/docs/package.json @@ -3,7 +3,7 @@ "private": true, "type": "module", "scripts": { - "build": "NODE_OPTIONS=\"--max-old-space-size=16384\" vocs build --searchIndex && cp 'dist/*/index.html' dist/404.html", + "build": "NODE_OPTIONS=\"--max-old-space-size=16384\" vocs build --searchIndex && cp dist/404/index.html dist/404.html", "check": "biome check . --write --unsafe", "check:ci": "biome check . --diagnostic-level=error", "check:types": "tsc --noEmit", diff --git a/docs/pages/*.mdx b/docs/pages/404.mdx similarity index 100% rename from docs/pages/*.mdx rename to docs/pages/404.mdx diff --git a/docs/vocs.config.tsx b/docs/vocs.config.tsx index 965d089191..1fdd9f60df 100644 --- a/docs/vocs.config.tsx +++ b/docs/vocs.config.tsx @@ -756,14 +756,20 @@ export default defineConfig({ vite: { plugins: [ { - // Vocs generates "/*" for *.mdx but checks for "*" in routes.tsx. - // This patches the route matching to recognize both paths for 404 handling. + // Vocs's default NotFound component shows a generic 404 page. + // This patches it to redirect to our custom /404 page instead. name: 'fix-404-route', transform(code, id) { if (!id.includes('vocs/_lib/app/routes')) return return code - .replace("path === '*'", "path === '*' || path === '/*'") - .replace("path !== '*'", "path !== '*' && path !== '/*'") + .replace( + "import { NotFound } from './components/NotFound.js';", + "import { Navigate } from 'react-router';", + ) + .replace( + '_jsx(NotFound, {})', + '_jsx(Navigate, { to: "/404", replace: true })', + ) }, }, { From 8b385976bff8b8449809538c5bea794c8a1d8fb2 Mon Sep 17 00:00:00 2001 From: Pierre Bertet Date: Fri, 16 Jan 2026 11:47:23 +0000 Subject: [PATCH 6/6] fix(docs): simplify 404 page to debug prerender issue Remove complex imports (icons, Card components) to test if they were causing silent prerender failures. Co-Authored-By: Claude Opus 4.5 --- docs/pages/404.mdx | 44 +++++++------------------------------------- 1 file changed, 7 insertions(+), 37 deletions(-) diff --git a/docs/pages/404.mdx b/docs/pages/404.mdx index 04bbedbb8c..0363f5fb09 100644 --- a/docs/pages/404.mdx +++ b/docs/pages/404.mdx @@ -3,43 +3,13 @@ title: Page not found description: The page you're looking for doesn't exist. Navigate back to Tempo documentation. --- -import LucideHome from '~icons/lucide/home' -import LucideBookOpen from '~icons/lucide/book-open' -import LucideRocket from '~icons/lucide/rocket' -import LucideSearch from '~icons/lucide/search' -import * as Card from "../components/Card.tsx" -
-
404
-

Page not found

-

- The page you're looking for doesn't exist or may have been moved. Try one of the options below to get back on track. +

404
+

Page not found

+

+ The page you're looking for doesn't exist or may have been moved.

+ + ← Back to home +
- - - - - - -