@vercel/geistdocs 1.21.1 → 1.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/internal/chat/copy-chat.d.ts.map +1 -1
  3. package/dist/internal/chat/copy-chat.js +1 -1
  4. package/dist/internal/chat/shell.d.ts.map +1 -1
  5. package/dist/internal/chat/shell.js +8 -3
  6. package/dist/internal/docs-page-error-boundary.d.ts +10 -0
  7. package/dist/internal/docs-page-error-boundary.d.ts.map +1 -0
  8. package/dist/internal/docs-page-error-boundary.js +7 -0
  9. package/dist/internal/localized-link.js +1 -1
  10. package/dist/internal/navbar/navbar-logo.d.ts.map +1 -1
  11. package/dist/internal/navbar/navbar-logo.js +2 -2
  12. package/dist/internal/page-breadcrumb.d.ts.map +1 -1
  13. package/dist/internal/page-breadcrumb.js +1 -1
  14. package/dist/internal/page-footer.d.ts.map +1 -1
  15. package/dist/internal/page-footer.js +2 -2
  16. package/dist/internal/search.d.ts.map +1 -1
  17. package/dist/internal/sidebar.d.ts.map +1 -1
  18. package/dist/internal/sidebar.js +14 -8
  19. package/dist/pages/docs.d.ts +1 -1
  20. package/dist/pages/docs.d.ts.map +1 -1
  21. package/dist/pages/docs.js +6 -2
  22. package/dist/proxy.d.ts.map +1 -1
  23. package/dist/proxy.js +2 -8
  24. package/dist/routes/llms.d.ts +5 -2
  25. package/dist/routes/llms.d.ts.map +1 -1
  26. package/dist/routes/llms.js +8 -10
  27. package/docs/agents.md +1 -1
  28. package/docs/llms.txt +69 -16
  29. package/docs/manifest.json +1 -1
  30. package/docs/pages/agent-readiness.md +2 -2
  31. package/docs/pages/configuration.md +6 -0
  32. package/docs/pages/llms-txt.md +3 -3
  33. package/docs/pages/md.md +3 -3
  34. package/docs/pages/migration.md +49 -5
  35. package/docs/pages/provider.md +2 -0
  36. package/docs/pages/versioned-docs.md +3 -2
  37. package/package.json +2 -2
  38. package/template/AGENTS.md +3 -0
  39. package/template/app/[lang]/(home)/layout.tsx +3 -2
  40. package/template/app/[lang]/.well-known/mcp.json/route.ts +3 -5
  41. package/template/app/[lang]/agents.md/route.ts +1 -1
  42. package/template/app/[lang]/docs/layout.tsx +3 -2
  43. package/template/app/[lang]/layout.tsx +7 -2
  44. package/template/app/[lang]/llms.mdx/[[...slug]]/route.ts +4 -5
  45. package/template/app/[lang]/llms.txt/route.ts +1 -1
  46. package/template/app/[lang]/rss.xml/route.ts +14 -7
  47. package/template/app/[lang]/sitemap.md/route.ts +4 -5
  48. package/template/app/sitemap.ts +5 -2
  49. package/template/content/docs/agent-readiness.mdx +2 -2
  50. package/template/content/docs/configuration.mdx +6 -0
  51. package/template/content/docs/llms-txt.cn.mdx +2 -2
  52. package/template/content/docs/llms-txt.mdx +3 -3
  53. package/template/content/docs/md.mdx +3 -3
  54. package/template/content/docs/migration.mdx +49 -5
  55. package/template/content/docs/provider.cn.mdx +2 -0
  56. package/template/content/docs/provider.mdx +2 -0
  57. package/template/content/docs/versioned-docs.mdx +3 -2
  58. package/template/lib/geistdocs/root-params.ts +5 -0
  59. package/template/next.config.ts +2 -0
  60. package/template/package.json +2 -2
package/docs/llms.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Documentation
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 1.21.1.
3
+ These docs are bundled with `@vercel/geistdocs` 1.22.0.
4
4
  They describe how to build package-backed Geistdocs sites and how to use the package APIs from generated project adapters.
5
5
 
6
6
  ## Documentation Index
@@ -438,6 +438,50 @@ If you are starting from a generated Geistdocs project and moving content into i
438
438
  pnpm dlx @vercel/geistdocs init --name my-docs
439
439
  ```
440
440
 
441
+ ## Enable Cache Components
442
+
443
+ Geistdocs uses Next.js Cache Components to prerender static application shells while dynamic content streams from the server. Enable Cache Components in `next.config.ts`:
444
+
445
+ ```ts title="next.config.ts"
446
+ import { createMDX } from "fumadocs-mdx/next";
447
+ import type { NextConfig } from "next";
448
+
449
+ const withMDX = createMDX();
450
+
451
+ const config: NextConfig = {
452
+ cacheComponents: true,
453
+ partialPrefetching: true,
454
+ };
455
+
456
+ export default withMDX(config);
457
+ ```
458
+
459
+ Every root dynamic parameter needs at least one value from `generateStaticParams`. For a site with a `[lang]` root segment, return every configured language from the root layout:
460
+
461
+ ```tsx title="app/[lang]/layout.tsx"
462
+ export const generateStaticParams = () => [{ lang: "en" }];
463
+ ```
464
+
465
+ Server Components can read the active language without passing `params` through each layout:
466
+
467
+ ```tsx title="app/[lang]/docs/layout.tsx"
468
+ import * as root from "next/root-params";
469
+
470
+ export default async function DocsLayout({ children }) {
471
+ const language = await root.lang();
472
+ // Use language to select the page tree.
473
+ return children;
474
+ }
475
+ ```
476
+
477
+ Keep using route context `params` in Route Handlers and Server Actions. Next.js does not support `next/root-params` in those contexts.
478
+
479
+ Remove `dynamic`, `revalidate`, and `fetchCache` exports from App Router pages and route handlers. Cache Components replaces those route segment options with `use cache` and `cacheLife`.
480
+
481
+ Keep `partialPrefetching` enabled so links reuse each route's static and cached content instead of prefetching every destination page separately.
482
+
483
+ For unknown HTML pages, browsers can receive the docs loading shell with a `200` response before the page resolves to the not-found UI. Crawlers wait for the complete response and receive `404`. Machine-readable Markdown routes keep their configured status behavior.
484
+
441
485
  ## Align Ask AI dependencies
442
486
 
443
487
  Geistdocs Ask AI uses AI SDK v6. Generated projects install `ai` v6 and `@ai-sdk/react` v3 so package-owned chat components and route helpers use the supported AI SDK APIs.
@@ -561,7 +605,7 @@ Add the package route helpers for machine-readable docs surfaces.
561
605
  import { createLlmsRoute } from "@vercel/geistdocs/routes/llms";
562
606
  import { geistdocsSource } from "@/lib/geistdocs/source";
563
607
 
564
- export const { GET, revalidate } = createLlmsRoute({
608
+ export const { GET } = createLlmsRoute({
565
609
  sources: [geistdocsSource],
566
610
  });
567
611
  ```
@@ -570,7 +614,7 @@ export const { GET, revalidate } = createLlmsRoute({
570
614
  import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
571
615
  import { geistdocsSource } from "@/lib/geistdocs/source";
572
616
 
573
- export const { GET, generateStaticParams, revalidate } =
617
+ export const { GET, generateStaticParams } =
574
618
  createDocsMarkdownRoute({
575
619
  notFound: {},
576
620
  source: geistdocsSource,
@@ -582,7 +626,7 @@ import { createSitemapMarkdownRoute } from "@vercel/geistdocs/routes/sitemap";
582
626
  import { config } from "@/lib/geistdocs/config";
583
627
  import { geistdocsSource } from "@/lib/geistdocs/source";
584
628
 
585
- export const { GET, generateStaticParams, revalidate, dynamic } =
629
+ export const { GET, generateStaticParams } =
586
630
  createSitemapMarkdownRoute({
587
631
  config,
588
632
  sources: [{ source: geistdocsSource.source }],
@@ -593,7 +637,7 @@ export const { GET, generateStaticParams, revalidate, dynamic } =
593
637
  import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
594
638
  import { config } from "@/lib/geistdocs/config";
595
639
 
596
- export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
640
+ export const { GET, generateStaticParams } = createAgentsRoute({
597
641
  config,
598
642
  });
599
643
  ```
@@ -602,7 +646,7 @@ export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
602
646
  import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
603
647
  import { config } from "@/lib/geistdocs/config";
604
648
 
605
- export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
649
+ export const { GET, generateStaticParams } = createMcpManifestRoute({
606
650
  config,
607
651
  });
608
652
  ```
@@ -983,6 +1027,8 @@ When Next.js mounts the application below a path, set the same value in `next.co
983
1027
  ```ts title="next.config.ts"
984
1028
  const config: NextConfig = {
985
1029
  basePath: "/docs",
1030
+ cacheComponents: true,
1031
+ partialPrefetching: true,
986
1032
  };
987
1033
  ```
988
1034
 
@@ -1115,6 +1161,10 @@ Set `openGraph.images` to `true` only when your site includes the Geistdocs OG r
1115
1161
 
1116
1162
  Section landing pages that use `title: Overview` produce a distinct document `<title>` automatically: Geistdocs substitutes the parent section label (for example, `Channels`) so browser tabs and search results stay meaningful instead of repeating "Overview". The visible page heading and breadcrumb are unchanged, and other pages keep their own title. Use the `metadata` callback to override the resolved title for a specific route.
1117
1163
 
1164
+ Geistdocs wraps resolved documentation pages in a Next.js error boundary. Unexpected rendering failures show a generic **Try again** action while the navbar and sidebar remain available. Framework signals such as `notFound()` and `redirect()` continue to use their standard Next.js behavior.
1165
+
1166
+ Package-owned links fully prefetch documentation destinations. Pages returned by `generateStaticParams` therefore navigate directly to their complete static content without showing transient fallback UI.
1167
+
1118
1168
  ## Package-owned runtime
1119
1169
 
1120
1170
  Do not edit files inside `node_modules/@vercel/geistdocs`. Update the package instead:
@@ -1628,6 +1678,8 @@ When users open the AI chat on desktop, the provider automatically adds padding
1628
1678
 
1629
1679
  The provider detects the screen size and chat state.
1630
1680
 
1681
+ If Ask AI fails while rendering, its panel shows **Try again** and **Close** actions. The error remains scoped to the chat panel, so the documentation page and navigation stay available.
1682
+
1631
1683
  ## Toast Notifications
1632
1684
 
1633
1685
  The provider includes a global toast notification system. Use it anywhere in your app:
@@ -1886,11 +1938,12 @@ docs root) instead:
1886
1938
  ```tsx title="app/[lang]/docs/layout.tsx"
1887
1939
  import { collectVersionSwitchPaths } from "@vercel/geistdocs/source";
1888
1940
  import { GeistdocsVersionSelect } from "@vercel/geistdocs/versions";
1941
+ import * as root from "next/root-params";
1889
1942
  import { config } from "@/lib/geistdocs/config";
1890
1943
  import { versions } from "@/lib/geistdocs/source";
1891
1944
 
1892
- const DocsLayout = async ({ children, params }) => {
1893
- const { lang } = await params;
1945
+ const DocsLayout = async ({ children }) => {
1946
+ const lang = await root.lang();
1894
1947
 
1895
1948
  return (
1896
1949
  <GeistdocsDocsLayout
@@ -2225,7 +2278,7 @@ The destination route uses `createDocsMarkdownRoute` to process the page and ret
2225
2278
  import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
2226
2279
  import { geistdocsSource } from "@/lib/geistdocs/source";
2227
2280
 
2228
- export const { GET, generateStaticParams, revalidate } =
2281
+ export const { GET, generateStaticParams } =
2229
2282
  createDocsMarkdownRoute({
2230
2283
  notFound: {},
2231
2284
  sources: [geistdocsSource],
@@ -2249,9 +2302,9 @@ All MDX components are processed and converted to plain Markdown equivalents.
2249
2302
 
2250
2303
  When a Markdown request does not match a page, Geistdocs returns an agent-readable `Page Not Found` response. It compares the requested path with visible page paths and titles, then links up to five likely matches with their descriptions. If no match is useful, the response links to `/llms.txt` instead.
2251
2304
 
2252
- For example, a request for `/docs/env-vars` can suggest `/docs/environment-variables.md`. The response uses a short cache lifetime and a `200` status because many agents discard useful bodies on `404` responses. It also sends `X-Robots-Tag: noindex` and no canonical link because the requested page does not exist. Regular HTML requests keep the app's standard not-found behavior.
2305
+ For example, a request for `/docs/env-vars` can suggest `/docs/environment-variables.md`. The response uses a short cache lifetime and returns a real `404` status. It also sends `X-Robots-Tag: noindex` and no canonical link because the requested page does not exist. Regular HTML requests keep the app's standard not-found behavior.
2253
2306
 
2254
- Enable this behavior with `notFound: {}`. Pass `notFound: { status: 404 }` to use a semantic HTTP status. Without `notFound`, Markdown requests use the standard Next.js not-found response.
2307
+ Enable this behavior with `notFound: {}`. Pass `notFound: { status: 410 }` for permanently removed pages. Legacy `status: 200` values are treated as `404` so missing pages always return a real error status. Without `notFound`, Markdown requests use the standard Next.js not-found response.
2255
2308
 
2256
2309
  If a custom `markdownRoutes` mapping changes the public path shape, set `notFound.getRequestedPath` to reconstruct the app-local public pathname. This also keeps page lookup and suggestions within the right source when a flattened route serves multiple sources:
2257
2310
 
@@ -2311,7 +2364,7 @@ Generated projects include a thin App Router adapter:
2311
2364
  import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
2312
2365
  import { config } from "@/lib/geistdocs/config";
2313
2366
 
2314
- export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
2367
+ export const { GET, generateStaticParams } = createAgentsRoute({
2315
2368
  config,
2316
2369
  });
2317
2370
  ```
@@ -2324,7 +2377,7 @@ Generated projects also include a thin adapter for MCP discovery:
2324
2377
  import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
2325
2378
  import { config } from "@/lib/geistdocs/config";
2326
2379
 
2327
- export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
2380
+ export const { GET, generateStaticParams } = createMcpManifestRoute({
2328
2381
  config,
2329
2382
  });
2330
2383
  ```
@@ -3207,7 +3260,7 @@ Generated projects use one documentation source:
3207
3260
  import { createLlmsRoute } from "@vercel/geistdocs/routes/llms";
3208
3261
  import { geistdocsSource } from "@/lib/geistdocs/source";
3209
3262
 
3210
- export const { GET, revalidate } = createLlmsRoute({
3263
+ export const { GET } = createLlmsRoute({
3211
3264
  source: geistdocsSource,
3212
3265
  });
3213
3266
  ```
@@ -3215,7 +3268,7 @@ export const { GET, revalidate } = createLlmsRoute({
3215
3268
  Sites with multiple content sections or versions can pass `sources`:
3216
3269
 
3217
3270
  ```ts title="app/[lang]/llms.txt/route.ts"
3218
- export const { GET, revalidate } = createLlmsRoute({
3271
+ export const { GET } = createLlmsRoute({
3219
3272
  sources: [docsSource, cookbookSource],
3220
3273
  });
3221
3274
  ```
@@ -3223,7 +3276,7 @@ export const { GET, revalidate } = createLlmsRoute({
3223
3276
  Use `filterPage` to exclude pages from `/llms.txt`, such as internal or preview-only docs:
3224
3277
 
3225
3278
  ```ts title="app/[lang]/llms.txt/route.ts"
3226
- export const { GET, revalidate } = createLlmsRoute({
3279
+ export const { GET } = createLlmsRoute({
3227
3280
  source: geistdocsSource,
3228
3281
  filterPage: (page) => !page.url.includes("/internal"),
3229
3282
  });
@@ -208,5 +208,5 @@
208
208
  }
209
209
  ],
210
210
  "source": "apps/template/content/docs",
211
- "version": "1.21.1"
211
+ "version": "1.22.0"
212
212
  }
@@ -40,7 +40,7 @@ Generated projects include a thin App Router adapter:
40
40
  import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
41
41
  import { config } from "@/lib/geistdocs/config";
42
42
 
43
- export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
43
+ export const { GET, generateStaticParams } = createAgentsRoute({
44
44
  config,
45
45
  });
46
46
  ```
@@ -53,7 +53,7 @@ Generated projects also include a thin adapter for MCP discovery:
53
53
  import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
54
54
  import { config } from "@/lib/geistdocs/config";
55
55
 
56
- export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
56
+ export const { GET, generateStaticParams } = createMcpManifestRoute({
57
57
  config,
58
58
  });
59
59
  ```
@@ -218,6 +218,8 @@ When Next.js mounts the application below a path, set the same value in `next.co
218
218
  ```ts title="next.config.ts"
219
219
  const config: NextConfig = {
220
220
  basePath: "/docs",
221
+ cacheComponents: true,
222
+ partialPrefetching: true,
221
223
  };
222
224
  ```
223
225
 
@@ -350,6 +352,10 @@ Set `openGraph.images` to `true` only when your site includes the Geistdocs OG r
350
352
 
351
353
  Section landing pages that use `title: Overview` produce a distinct document `<title>` automatically: Geistdocs substitutes the parent section label (for example, `Channels`) so browser tabs and search results stay meaningful instead of repeating "Overview". The visible page heading and breadcrumb are unchanged, and other pages keep their own title. Use the `metadata` callback to override the resolved title for a specific route.
352
354
 
355
+ Geistdocs wraps resolved documentation pages in a Next.js error boundary. Unexpected rendering failures show a generic **Try again** action while the navbar and sidebar remain available. Framework signals such as `notFound()` and `redirect()` continue to use their standard Next.js behavior.
356
+
357
+ Package-owned links fully prefetch documentation destinations. Pages returned by `generateStaticParams` therefore navigate directly to their complete static content without showing transient fallback UI.
358
+
353
359
  ## Package-owned runtime
354
360
 
355
361
  Do not edit files inside `node_modules/@vercel/geistdocs`. Update the package instead:
@@ -59,7 +59,7 @@ Generated projects use one documentation source:
59
59
  import { createLlmsRoute } from "@vercel/geistdocs/routes/llms";
60
60
  import { geistdocsSource } from "@/lib/geistdocs/source";
61
61
 
62
- export const { GET, revalidate } = createLlmsRoute({
62
+ export const { GET } = createLlmsRoute({
63
63
  source: geistdocsSource,
64
64
  });
65
65
  ```
@@ -67,7 +67,7 @@ export const { GET, revalidate } = createLlmsRoute({
67
67
  Sites with multiple content sections or versions can pass `sources`:
68
68
 
69
69
  ```ts title="app/[lang]/llms.txt/route.ts"
70
- export const { GET, revalidate } = createLlmsRoute({
70
+ export const { GET } = createLlmsRoute({
71
71
  sources: [docsSource, cookbookSource],
72
72
  });
73
73
  ```
@@ -75,7 +75,7 @@ export const { GET, revalidate } = createLlmsRoute({
75
75
  Use `filterPage` to exclude pages from `/llms.txt`, such as internal or preview-only docs:
76
76
 
77
77
  ```ts title="app/[lang]/llms.txt/route.ts"
78
- export const { GET, revalidate } = createLlmsRoute({
78
+ export const { GET } = createLlmsRoute({
79
79
  source: geistdocsSource,
80
80
  filterPage: (page) => !page.url.includes("/internal"),
81
81
  });
package/docs/pages/md.md CHANGED
@@ -69,7 +69,7 @@ The destination route uses `createDocsMarkdownRoute` to process the page and ret
69
69
  import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
70
70
  import { geistdocsSource } from "@/lib/geistdocs/source";
71
71
 
72
- export const { GET, generateStaticParams, revalidate } =
72
+ export const { GET, generateStaticParams } =
73
73
  createDocsMarkdownRoute({
74
74
  notFound: {},
75
75
  sources: [geistdocsSource],
@@ -93,9 +93,9 @@ All MDX components are processed and converted to plain Markdown equivalents.
93
93
 
94
94
  When a Markdown request does not match a page, Geistdocs returns an agent-readable `Page Not Found` response. It compares the requested path with visible page paths and titles, then links up to five likely matches with their descriptions. If no match is useful, the response links to `/llms.txt` instead.
95
95
 
96
- For example, a request for `/docs/env-vars` can suggest `/docs/environment-variables.md`. The response uses a short cache lifetime and a `200` status because many agents discard useful bodies on `404` responses. It also sends `X-Robots-Tag: noindex` and no canonical link because the requested page does not exist. Regular HTML requests keep the app's standard not-found behavior.
96
+ For example, a request for `/docs/env-vars` can suggest `/docs/environment-variables.md`. The response uses a short cache lifetime and returns a real `404` status. It also sends `X-Robots-Tag: noindex` and no canonical link because the requested page does not exist. Regular HTML requests keep the app's standard not-found behavior.
97
97
 
98
- Enable this behavior with `notFound: {}`. Pass `notFound: { status: 404 }` to use a semantic HTTP status. Without `notFound`, Markdown requests use the standard Next.js not-found response.
98
+ Enable this behavior with `notFound: {}`. Pass `notFound: { status: 410 }` for permanently removed pages. Legacy `status: 200` values are treated as `404` so missing pages always return a real error status. Without `notFound`, Markdown requests use the standard Next.js not-found response.
99
99
 
100
100
  If a custom `markdownRoutes` mapping changes the public path shape, set `notFound.getRequestedPath` to reconstruct the app-local public pathname. This also keeps page lookup and suggestions within the right source when a flattened route serves multiple sources:
101
101
 
@@ -58,6 +58,50 @@ If you are starting from a generated Geistdocs project and moving content into i
58
58
  pnpm dlx @vercel/geistdocs init --name my-docs
59
59
  ```
60
60
 
61
+ ## Enable Cache Components
62
+
63
+ Geistdocs uses Next.js Cache Components to prerender static application shells while dynamic content streams from the server. Enable Cache Components in `next.config.ts`:
64
+
65
+ ```ts title="next.config.ts"
66
+ import { createMDX } from "fumadocs-mdx/next";
67
+ import type { NextConfig } from "next";
68
+
69
+ const withMDX = createMDX();
70
+
71
+ const config: NextConfig = {
72
+ cacheComponents: true,
73
+ partialPrefetching: true,
74
+ };
75
+
76
+ export default withMDX(config);
77
+ ```
78
+
79
+ Every root dynamic parameter needs at least one value from `generateStaticParams`. For a site with a `[lang]` root segment, return every configured language from the root layout:
80
+
81
+ ```tsx title="app/[lang]/layout.tsx"
82
+ export const generateStaticParams = () => [{ lang: "en" }];
83
+ ```
84
+
85
+ Server Components can read the active language without passing `params` through each layout:
86
+
87
+ ```tsx title="app/[lang]/docs/layout.tsx"
88
+ import * as root from "next/root-params";
89
+
90
+ export default async function DocsLayout({ children }) {
91
+ const language = await root.lang();
92
+ // Use language to select the page tree.
93
+ return children;
94
+ }
95
+ ```
96
+
97
+ Keep using route context `params` in Route Handlers and Server Actions. Next.js does not support `next/root-params` in those contexts.
98
+
99
+ Remove `dynamic`, `revalidate`, and `fetchCache` exports from App Router pages and route handlers. Cache Components replaces those route segment options with `use cache` and `cacheLife`.
100
+
101
+ Keep `partialPrefetching` enabled so links reuse each route's static and cached content instead of prefetching every destination page separately.
102
+
103
+ For unknown HTML pages, browsers can receive the docs loading shell with a `200` response before the page resolves to the not-found UI. Crawlers wait for the complete response and receive `404`. Machine-readable Markdown routes keep their configured status behavior.
104
+
61
105
  ## Align Ask AI dependencies
62
106
 
63
107
  Geistdocs Ask AI uses AI SDK v6. Generated projects install `ai` v6 and `@ai-sdk/react` v3 so package-owned chat components and route helpers use the supported AI SDK APIs.
@@ -181,7 +225,7 @@ Add the package route helpers for machine-readable docs surfaces.
181
225
  import { createLlmsRoute } from "@vercel/geistdocs/routes/llms";
182
226
  import { geistdocsSource } from "@/lib/geistdocs/source";
183
227
 
184
- export const { GET, revalidate } = createLlmsRoute({
228
+ export const { GET } = createLlmsRoute({
185
229
  sources: [geistdocsSource],
186
230
  });
187
231
  ```
@@ -190,7 +234,7 @@ export const { GET, revalidate } = createLlmsRoute({
190
234
  import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
191
235
  import { geistdocsSource } from "@/lib/geistdocs/source";
192
236
 
193
- export const { GET, generateStaticParams, revalidate } =
237
+ export const { GET, generateStaticParams } =
194
238
  createDocsMarkdownRoute({
195
239
  notFound: {},
196
240
  source: geistdocsSource,
@@ -202,7 +246,7 @@ import { createSitemapMarkdownRoute } from "@vercel/geistdocs/routes/sitemap";
202
246
  import { config } from "@/lib/geistdocs/config";
203
247
  import { geistdocsSource } from "@/lib/geistdocs/source";
204
248
 
205
- export const { GET, generateStaticParams, revalidate, dynamic } =
249
+ export const { GET, generateStaticParams } =
206
250
  createSitemapMarkdownRoute({
207
251
  config,
208
252
  sources: [{ source: geistdocsSource.source }],
@@ -213,7 +257,7 @@ export const { GET, generateStaticParams, revalidate, dynamic } =
213
257
  import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
214
258
  import { config } from "@/lib/geistdocs/config";
215
259
 
216
- export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
260
+ export const { GET, generateStaticParams } = createAgentsRoute({
217
261
  config,
218
262
  });
219
263
  ```
@@ -222,7 +266,7 @@ export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
222
266
  import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
223
267
  import { config } from "@/lib/geistdocs/config";
224
268
 
225
- export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
269
+ export const { GET, generateStaticParams } = createMcpManifestRoute({
226
270
  config,
227
271
  });
228
272
  ```
@@ -53,6 +53,8 @@ When users open the AI chat on desktop, the provider automatically adds padding
53
53
 
54
54
  The provider detects the screen size and chat state.
55
55
 
56
+ If Ask AI fails while rendering, its panel shows **Try again** and **Close** actions. The error remains scoped to the chat panel, so the documentation page and navigation stay available.
57
+
56
58
  ## Toast Notifications
57
59
 
58
60
  The provider includes a global toast notification system. Use it anywhere in your app:
@@ -231,11 +231,12 @@ docs root) instead:
231
231
  ```tsx title="app/[lang]/docs/layout.tsx"
232
232
  import { collectVersionSwitchPaths } from "@vercel/geistdocs/source";
233
233
  import { GeistdocsVersionSelect } from "@vercel/geistdocs/versions";
234
+ import * as root from "next/root-params";
234
235
  import { config } from "@/lib/geistdocs/config";
235
236
  import { versions } from "@/lib/geistdocs/source";
236
237
 
237
- const DocsLayout = async ({ children, params }) => {
238
- const { lang } = await params;
238
+ const DocsLayout = async ({ children }) => {
239
+ const lang = await root.lang();
239
240
 
240
241
  return (
241
242
  <GeistdocsDocsLayout
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@vercel/geistdocs",
3
3
  "description": "Runtime and CLI for Geistdocs projects.",
4
- "version": "1.21.1",
4
+ "version": "1.22.0",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -262,7 +262,7 @@
262
262
  "@orama/tokenizers": "^3.1.16",
263
263
  "@streamdown/cjk": "^1.0.1",
264
264
  "@streamdown/code": "^1.0.1",
265
- "@vercel/agent-readability": "^0.5.1",
265
+ "@vercel/agent-readability": "^0.6.0",
266
266
  "@vercel/oidc": "^3.4.1",
267
267
  "ai": "^6.0.132",
268
268
  "class-variance-authority": "^0.7.1",
@@ -52,6 +52,9 @@ Use these instructions when an AI coding agent edits this project.
52
52
  ## Routing and proxy guidelines
53
53
 
54
54
  - Keep App Router route files as thin adapters around package helpers such as `createDocsPage`, `createChatRoute`, `createLlmsRoute`, and `createProxy`.
55
+ - Keep `cacheComponents: true` and `partialPrefetching: true` in `next.config.ts`. Do not export `dynamic`, `revalidate`, or `fetchCache` from App Router pages or route handlers.
56
+ - Read `[lang]` from `next/root-params` in Server Components. Keep route context `params` in Route Handlers and Server Actions.
57
+ - Use `prefetch={true}` for app-owned links to fully static documentation pages so navigation does not stop at the generic route shell.
55
58
  - Keep `export const config` in `proxy.ts` as a static object. Next.js must parse proxy matchers at build time.
56
59
  - Use proxy matcher exclusions that only match `/api` and `/api/...`, such as `api(?:/|$)`. Do not exclude broad prefixes like `api`, because that also excludes routes such as `/api-reference`.
57
60
  - Preserve markdown negotiation unless the task explicitly changes AI-readable output. Geistdocs serves `/agents.md`, `/llms.txt`, `/.well-known/mcp.json`, and per-page Markdown for `.md`, `.mdx`, `Accept: text/markdown`, and AI-agent requests.
@@ -1,9 +1,10 @@
1
1
  import { GeistdocsHomeLayout } from "@vercel/geistdocs/home-layout";
2
2
  import { config } from "@/lib/geistdocs/config";
3
+ import { getRootLang } from "@/lib/geistdocs/root-params";
3
4
  import { source } from "@/lib/geistdocs/source";
4
5
 
5
- const Layout = async ({ children, params }: LayoutProps<"/[lang]">) => {
6
- const { lang } = await params;
6
+ const Layout = async ({ children }: LayoutProps<"/[lang]">) => {
7
+ const lang = await getRootLang();
7
8
 
8
9
  return (
9
10
  <GeistdocsHomeLayout config={config} tree={source.pageTree[lang]}>
@@ -1,8 +1,6 @@
1
1
  import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
2
2
  import { config } from "@/lib/geistdocs/config";
3
3
 
4
- export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute(
5
- {
6
- config,
7
- }
8
- );
4
+ export const { GET, generateStaticParams } = createMcpManifestRoute({
5
+ config,
6
+ });
@@ -1,6 +1,6 @@
1
1
  import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
2
2
  import { config } from "@/lib/geistdocs/config";
3
3
 
4
- export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
4
+ export const { GET, generateStaticParams } = createAgentsRoute({
5
5
  config,
6
6
  });
@@ -1,8 +1,9 @@
1
1
  import { DocsLayout } from "@/components/geistdocs/docs-layout";
2
+ import { getRootLang } from "@/lib/geistdocs/root-params";
2
3
  import { source } from "@/lib/geistdocs/source";
3
4
 
4
- const Layout = async ({ children, params }: LayoutProps<"/[lang]/docs">) => {
5
- const { lang } = await params;
5
+ const Layout = async ({ children }: LayoutProps<"/[lang]/docs">) => {
6
+ const lang = await getRootLang();
6
7
 
7
8
  return (
8
9
  <div className="bg-background-200">
@@ -4,10 +4,15 @@ import { Navbar } from "@vercel/geistdocs/navbar";
4
4
  import { GeistdocsProvider } from "@/components/geistdocs/provider";
5
5
  import { config } from "@/lib/geistdocs/config";
6
6
  import { mono, sans } from "@/lib/geistdocs/fonts";
7
+ import { i18n } from "@/lib/geistdocs/i18n";
8
+ import { getRootLang } from "@/lib/geistdocs/root-params";
7
9
  import { cn } from "@/lib/utils";
8
10
 
9
- const Layout = async ({ children, params }: LayoutProps<"/[lang]">) => {
10
- const { lang } = await params;
11
+ export const generateStaticParams = () =>
12
+ i18n.languages.map((lang) => ({ lang }));
13
+
14
+ const Layout = async ({ children }: LayoutProps<"/[lang]">) => {
15
+ const lang = await getRootLang();
11
16
 
12
17
  return (
13
18
  <html
@@ -1,8 +1,7 @@
1
1
  import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
2
2
  import { geistdocsSource } from "@/lib/geistdocs/source";
3
3
 
4
- export const { GET, generateStaticParams, revalidate } =
5
- createDocsMarkdownRoute({
6
- notFound: {},
7
- sources: [geistdocsSource],
8
- });
4
+ export const { GET, generateStaticParams } = createDocsMarkdownRoute({
5
+ notFound: {},
6
+ sources: [geistdocsSource],
7
+ });
@@ -1,6 +1,6 @@
1
1
  import { createLlmsRoute } from "@vercel/geistdocs/routes/llms";
2
2
  import { geistdocsSource } from "@/lib/geistdocs/source";
3
3
 
4
- export const { GET, revalidate } = createLlmsRoute({
4
+ export const { GET } = createLlmsRoute({
5
5
  sources: [geistdocsSource],
6
6
  });
@@ -1,5 +1,6 @@
1
1
  import { getPublicPath } from "@vercel/geistdocs/config";
2
2
  import { Feed } from "feed";
3
+ import { cacheLife } from "next/cache";
3
4
  import type { NextRequest } from "next/server";
4
5
  import { title } from "@/geistdocs";
5
6
  import { config } from "@/lib/geistdocs/config";
@@ -10,13 +11,11 @@ const baseUrl = `${protocol}://${process.env.NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTI
10
11
  const sitePath = getPublicPath("/", config.basePath);
11
12
  const siteUrl = sitePath === "/" ? baseUrl : `${baseUrl}${sitePath}`;
12
13
 
13
- export const revalidate = false;
14
+ // biome-ignore lint/suspicious/useAwait: Next.js requires cached functions to be async.
15
+ const getFeed = async (lang: string) => {
16
+ "use cache";
17
+ cacheLife("max");
14
18
 
15
- export const GET = async (
16
- _req: NextRequest,
17
- { params }: RouteContext<"/[lang]/rss.xml">
18
- ) => {
19
- const { lang } = await params;
20
19
  const feed = new Feed({
21
20
  title,
22
21
  id: siteUrl,
@@ -46,7 +45,15 @@ export const GET = async (
46
45
  });
47
46
  }
48
47
 
49
- const rss = feed.rss2();
48
+ return feed.rss2();
49
+ };
50
+
51
+ export const GET = async (
52
+ _req: NextRequest,
53
+ { params }: RouteContext<"/[lang]/rss.xml">
54
+ ) => {
55
+ const { lang } = await params;
56
+ const rss = await getFeed(lang);
50
57
 
51
58
  return new Response(rss, {
52
59
  headers: {
@@ -2,8 +2,7 @@ import { createSitemapMarkdownRoute } from "@vercel/geistdocs/routes/sitemap";
2
2
  import { config } from "@/lib/geistdocs/config";
3
3
  import { geistdocsSource } from "@/lib/geistdocs/source";
4
4
 
5
- export const { GET, generateStaticParams, revalidate, dynamic } =
6
- createSitemapMarkdownRoute({
7
- config,
8
- sources: [{ source: geistdocsSource }],
9
- });
5
+ export const { GET, generateStaticParams } = createSitemapMarkdownRoute({
6
+ config,
7
+ sources: [{ source: geistdocsSource }],
8
+ });
@@ -1,13 +1,16 @@
1
1
  import type { MetadataRoute } from "next";
2
+ import { cacheLife } from "next/cache";
2
3
 
3
4
  import { source } from "@/lib/geistdocs/source";
4
5
 
5
6
  const protocol = process.env.NODE_ENV === "production" ? "https" : "http";
6
7
  const baseUrl = `${protocol}://${process.env.NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL}`;
7
8
 
8
- export const revalidate = false;
9
+ // biome-ignore lint/suspicious/useAwait: Next.js requires cached functions to be async.
10
+ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
11
+ "use cache";
12
+ cacheLife("max");
9
13
 
10
- export default function sitemap(): MetadataRoute.Sitemap {
11
14
  const url = (path: string): string => new URL(path, baseUrl).toString();
12
15
 
13
16
  const pages: MetadataRoute.Sitemap = [];
@@ -38,7 +38,7 @@ Generated projects include a thin App Router adapter:
38
38
  import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
39
39
  import { config } from "@/lib/geistdocs/config";
40
40
 
41
- export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
41
+ export const { GET, generateStaticParams } = createAgentsRoute({
42
42
  config,
43
43
  });
44
44
  ```
@@ -51,7 +51,7 @@ Generated projects also include a thin adapter for MCP discovery:
51
51
  import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
52
52
  import { config } from "@/lib/geistdocs/config";
53
53
 
54
- export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
54
+ export const { GET, generateStaticParams } = createMcpManifestRoute({
55
55
  config,
56
56
  });
57
57
  ```