@vercel/geistdocs 1.21.1 → 1.23.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 (104) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +2 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/footer.d.ts.map +1 -1
  5. package/dist/footer.js +5 -0
  6. package/dist/home-layout.d.ts +2 -2
  7. package/dist/home-layout.d.ts.map +1 -1
  8. package/dist/home-layout.js +52 -18
  9. package/dist/internal/chat/copy-chat.d.ts.map +1 -1
  10. package/dist/internal/chat/copy-chat.js +1 -1
  11. package/dist/internal/chat/shell.d.ts.map +1 -1
  12. package/dist/internal/chat/shell.js +8 -3
  13. package/dist/internal/docs-page-error-boundary.d.ts +10 -0
  14. package/dist/internal/docs-page-error-boundary.d.ts.map +1 -0
  15. package/dist/internal/docs-page-error-boundary.js +7 -0
  16. package/dist/internal/localized-link.js +2 -2
  17. package/dist/internal/navbar/navbar-logo.d.ts.map +1 -1
  18. package/dist/internal/navbar/navbar-logo.js +2 -2
  19. package/dist/internal/page-actions-client.d.ts.map +1 -1
  20. package/dist/internal/page-actions-client.js +18 -2
  21. package/dist/internal/page-breadcrumb.d.ts.map +1 -1
  22. package/dist/internal/page-breadcrumb.js +1 -1
  23. package/dist/internal/page-footer.d.ts.map +1 -1
  24. package/dist/internal/page-footer.js +2 -2
  25. package/dist/internal/search.d.ts.map +1 -1
  26. package/dist/internal/sidebar.d.ts.map +1 -1
  27. package/dist/internal/sidebar.js +14 -8
  28. package/dist/localize-href.d.ts +6 -0
  29. package/dist/localize-href.d.ts.map +1 -0
  30. package/dist/{internal/localize-href.js → localize-href.js} +2 -5
  31. package/dist/{internal/page-visibility.d.ts → page-visibility.d.ts} +1 -1
  32. package/dist/page-visibility.d.ts.map +1 -0
  33. package/dist/pages/docs.d.ts +3 -3
  34. package/dist/pages/docs.d.ts.map +1 -1
  35. package/dist/pages/docs.js +16 -7
  36. package/dist/proxy.d.ts +1 -1
  37. package/dist/proxy.d.ts.map +1 -1
  38. package/dist/proxy.js +15 -10
  39. package/dist/routes/agents.d.ts.map +1 -1
  40. package/dist/routes/agents.js +4 -4
  41. package/dist/routes/chat.js +1 -1
  42. package/dist/routes/llms.d.ts +5 -2
  43. package/dist/routes/llms.d.ts.map +1 -1
  44. package/dist/routes/llms.js +9 -11
  45. package/dist/routes/not-found.d.ts +14 -0
  46. package/dist/routes/not-found.d.ts.map +1 -0
  47. package/dist/routes/not-found.js +74 -0
  48. package/dist/routes/search.js +1 -1
  49. package/dist/routes/sitemap.d.ts +1 -1
  50. package/dist/routes/sitemap.d.ts.map +1 -1
  51. package/dist/routes/sitemap.js +1 -1
  52. package/docs/agents.md +1 -1
  53. package/docs/llms.txt +76 -19
  54. package/docs/manifest.json +1 -1
  55. package/docs/pages/agent-readiness.md +3 -3
  56. package/docs/pages/configuration.md +6 -0
  57. package/docs/pages/env.md +2 -2
  58. package/docs/pages/llms-txt.md +3 -3
  59. package/docs/pages/md.md +5 -3
  60. package/docs/pages/migration.md +49 -5
  61. package/docs/pages/provider.md +2 -0
  62. package/docs/pages/proxy.md +2 -0
  63. package/docs/pages/versioned-docs.md +3 -2
  64. package/package.json +14 -2
  65. package/template/AGENTS.md +3 -0
  66. package/template/app/[lang]/(home)/components/text-grid-section.tsx +25 -11
  67. package/template/app/[lang]/(home)/layout.tsx +3 -2
  68. package/template/app/[lang]/(home)/opengraph-image.tsx +40 -0
  69. package/template/app/[lang]/(home)/page.tsx +143 -89
  70. package/template/app/[lang]/.well-known/mcp.json/route.ts +3 -5
  71. package/template/app/[lang]/[...not-found]/route.ts +4 -0
  72. package/template/app/[lang]/agents.md/route.ts +1 -1
  73. package/template/app/[lang]/docs/layout.tsx +3 -2
  74. package/template/app/[lang]/layout.tsx +14 -2
  75. package/template/app/[lang]/llms.mdx/[[...slug]]/route.ts +4 -5
  76. package/template/app/[lang]/llms.txt/route.ts +1 -1
  77. package/template/app/[lang]/not-found.tsx +37 -0
  78. package/template/app/[lang]/rss.xml/route.ts +17 -11
  79. package/template/app/[lang]/sitemap.md/route.ts +4 -5
  80. package/template/app/robots.ts +4 -4
  81. package/template/app/sitemap.ts +16 -10
  82. package/template/content/docs/agent-readiness.mdx +3 -3
  83. package/template/content/docs/configuration.mdx +6 -0
  84. package/template/content/docs/env.mdx +2 -2
  85. package/template/content/docs/llms-txt.cn.mdx +2 -2
  86. package/template/content/docs/llms-txt.mdx +3 -3
  87. package/template/content/docs/md.mdx +5 -3
  88. package/template/content/docs/migration.mdx +49 -5
  89. package/template/content/docs/provider.cn.mdx +2 -0
  90. package/template/content/docs/provider.mdx +2 -0
  91. package/template/content/docs/proxy.mdx +2 -0
  92. package/template/content/docs/versioned-docs.mdx +3 -2
  93. package/template/lib/geistdocs/config.tsx +2 -0
  94. package/template/lib/geistdocs/public-path.ts +14 -0
  95. package/template/lib/geistdocs/root-params.ts +5 -0
  96. package/template/lib/geistdocs/site-url-warning.ts +10 -0
  97. package/template/lib/geistdocs/site-url.ts +33 -0
  98. package/template/next.config.ts +2 -10
  99. package/template/package.json +2 -2
  100. package/dist/internal/localize-href.d.ts +0 -9
  101. package/dist/internal/localize-href.d.ts.map +0 -1
  102. package/dist/internal/page-visibility.d.ts.map +0 -1
  103. package/template/app/[lang]/(home)/components/templates.tsx +0 -48
  104. /package/dist/{internal/page-visibility.js → page-visibility.js} +0 -0
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.23.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
@@ -314,9 +314,9 @@ The Vertex deployment does not need a Geistdocs-specific environment variable. A
314
314
 
315
315
  ## `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`
316
316
 
317
- The production URL of the Geistdocs site. This is automatically set when deploying to Vercel.
317
+ The production URL of the Geistdocs site. Geistdocs uses it for canonical and Open Graph metadata, product JSON-LD, `sitemap.xml`, `robots.txt`, and RSS links. Vercel sets this variable automatically.
318
318
 
319
- It should be in the format `localhost:3000` (i.e. without the protocol prefix). This is how Vercel sets the environment variable when deploying to a project.
319
+ Set this variable explicitly when deploying outside Vercel. Use a hostname such as `docs.example.com` or a full `http` or `https` URL. Local development falls back to `http://localhost:3000`. A production build with a missing or malformed value emits a warning and omits default canonical and product JSON-LD URLs. Its `sitemap.xml`, `robots.txt` sitemap directive, RSS links, and generated Open Graph image URLs continue to use the localhost fallback, so treat the warning as a deployment blocker. Geistdocs does not use the deployment-specific `VERCEL_URL` for canonical surfaces.
320
320
 
321
321
 
322
322
  ---
@@ -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
@@ -2046,6 +2099,8 @@ const proxy = createProxy({
2046
2099
 
2047
2100
  Define `content` sections in `lib/geistdocs/config.tsx` to infer standard Markdown route mappings from each section route. The package still serves `/llms.txt` and individual page Markdown through route helpers; the proxy uses these mappings for `.md`, `.mdx`, `Accept: text/markdown`, and AI-agent requests.
2048
2101
 
2102
+ When `agent` metadata is configured, a request to the homepage with `Accept: text/markdown` returns the generated `/agents.md` content. This gives agents a product overview and focused discovery links without treating every application route as documentation.
2103
+
2049
2104
  Geistdocs does not infer Markdown mappings for `content` sections with `route: "/"`. A root catch-all such as `/*path` can make a homepage or other application routes look like documentation. Use explicit `markdownRoutes` for root-mounted docs.
2050
2105
 
2051
2106
  ```tsx title="lib/geistdocs/config.tsx"
@@ -2225,7 +2280,7 @@ The destination route uses `createDocsMarkdownRoute` to process the page and ret
2225
2280
  import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
2226
2281
  import { geistdocsSource } from "@/lib/geistdocs/source";
2227
2282
 
2228
- export const { GET, generateStaticParams, revalidate } =
2283
+ export const { GET, generateStaticParams } =
2229
2284
  createDocsMarkdownRoute({
2230
2285
  notFound: {},
2231
2286
  sources: [geistdocsSource],
@@ -2249,9 +2304,11 @@ All MDX components are processed and converted to plain Markdown equivalents.
2249
2304
 
2250
2305
  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
2306
 
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.
2307
+ 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.
2308
+
2309
+ Generated projects also include a catch-all route for unknown application paths outside configured documentation sections. It returns a concise Markdown 404 with links to the docs, `sitemap.md`, and `llms.txt` for agent or `Accept: text/markdown` requests. Browser requests receive the same recovery links as HTML.
2253
2310
 
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.
2311
+ 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
2312
 
2256
2313
  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
2314
 
@@ -2290,7 +2347,7 @@ Geistdocs can generate `/agents.md` and `/.well-known/mcp.json` discovery files
2290
2347
 
2291
2348
  ## What it provides
2292
2349
 
2293
- The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. The optional `/.well-known/mcp.json` route advertises configured MCP servers without running an MCP server inside Geistdocs.
2350
+ The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. Its product section states when to use the documented product, and the homepage serves the same guidance when an agent requests `text/markdown`. The optional `/.well-known/mcp.json` route advertises configured MCP servers without running an MCP server inside Geistdocs.
2294
2351
 
2295
2352
  It can include:
2296
2353
 
@@ -2311,7 +2368,7 @@ Generated projects include a thin App Router adapter:
2311
2368
  import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
2312
2369
  import { config } from "@/lib/geistdocs/config";
2313
2370
 
2314
- export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
2371
+ export const { GET, generateStaticParams } = createAgentsRoute({
2315
2372
  config,
2316
2373
  });
2317
2374
  ```
@@ -2324,7 +2381,7 @@ Generated projects also include a thin adapter for MCP discovery:
2324
2381
  import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
2325
2382
  import { config } from "@/lib/geistdocs/config";
2326
2383
 
2327
- export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
2384
+ export const { GET, generateStaticParams } = createMcpManifestRoute({
2328
2385
  config,
2329
2386
  });
2330
2387
  ```
@@ -3207,7 +3264,7 @@ Generated projects use one documentation source:
3207
3264
  import { createLlmsRoute } from "@vercel/geistdocs/routes/llms";
3208
3265
  import { geistdocsSource } from "@/lib/geistdocs/source";
3209
3266
 
3210
- export const { GET, revalidate } = createLlmsRoute({
3267
+ export const { GET } = createLlmsRoute({
3211
3268
  source: geistdocsSource,
3212
3269
  });
3213
3270
  ```
@@ -3215,7 +3272,7 @@ export const { GET, revalidate } = createLlmsRoute({
3215
3272
  Sites with multiple content sections or versions can pass `sources`:
3216
3273
 
3217
3274
  ```ts title="app/[lang]/llms.txt/route.ts"
3218
- export const { GET, revalidate } = createLlmsRoute({
3275
+ export const { GET } = createLlmsRoute({
3219
3276
  sources: [docsSource, cookbookSource],
3220
3277
  });
3221
3278
  ```
@@ -3223,7 +3280,7 @@ export const { GET, revalidate } = createLlmsRoute({
3223
3280
  Use `filterPage` to exclude pages from `/llms.txt`, such as internal or preview-only docs:
3224
3281
 
3225
3282
  ```ts title="app/[lang]/llms.txt/route.ts"
3226
- export const { GET, revalidate } = createLlmsRoute({
3283
+ export const { GET } = createLlmsRoute({
3227
3284
  source: geistdocsSource,
3228
3285
  filterPage: (page) => !page.url.includes("/internal"),
3229
3286
  });
@@ -208,5 +208,5 @@
208
208
  }
209
209
  ],
210
210
  "source": "apps/template/content/docs",
211
- "version": "1.21.1"
211
+ "version": "1.23.0"
212
212
  }
@@ -19,7 +19,7 @@ Geistdocs can generate `/agents.md` and `/.well-known/mcp.json` discovery files
19
19
 
20
20
  ## What it provides
21
21
 
22
- The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. The optional `/.well-known/mcp.json` route advertises configured MCP servers without running an MCP server inside Geistdocs.
22
+ The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. Its product section states when to use the documented product, and the homepage serves the same guidance when an agent requests `text/markdown`. The optional `/.well-known/mcp.json` route advertises configured MCP servers without running an MCP server inside Geistdocs.
23
23
 
24
24
  It can include:
25
25
 
@@ -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:
package/docs/pages/env.md CHANGED
@@ -57,6 +57,6 @@ The Vertex deployment does not need a Geistdocs-specific environment variable. A
57
57
 
58
58
  ## `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`
59
59
 
60
- The production URL of the Geistdocs site. This is automatically set when deploying to Vercel.
60
+ The production URL of the Geistdocs site. Geistdocs uses it for canonical and Open Graph metadata, product JSON-LD, `sitemap.xml`, `robots.txt`, and RSS links. Vercel sets this variable automatically.
61
61
 
62
- It should be in the format `localhost:3000` (i.e. without the protocol prefix). This is how Vercel sets the environment variable when deploying to a project.
62
+ Set this variable explicitly when deploying outside Vercel. Use a hostname such as `docs.example.com` or a full `http` or `https` URL. Local development falls back to `http://localhost:3000`. A production build with a missing or malformed value emits a warning and omits default canonical and product JSON-LD URLs. Its `sitemap.xml`, `robots.txt` sitemap directive, RSS links, and generated Open Graph image URLs continue to use the localhost fallback, so treat the warning as a deployment blocker. Geistdocs does not use the deployment-specific `VERCEL_URL` for canonical surfaces.
@@ -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,11 @@ 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
+ Generated projects also include a catch-all route for unknown application paths outside configured documentation sections. It returns a concise Markdown 404 with links to the docs, `sitemap.md`, and `llms.txt` for agent or `Accept: text/markdown` requests. Browser requests receive the same recovery links as HTML.
99
+
100
+ 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
101
 
100
102
  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
103
 
@@ -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:
@@ -89,6 +89,8 @@ const proxy = createProxy({
89
89
 
90
90
  Define `content` sections in `lib/geistdocs/config.tsx` to infer standard Markdown route mappings from each section route. The package still serves `/llms.txt` and individual page Markdown through route helpers; the proxy uses these mappings for `.md`, `.mdx`, `Accept: text/markdown`, and AI-agent requests.
91
91
 
92
+ When `agent` metadata is configured, a request to the homepage with `Accept: text/markdown` returns the generated `/agents.md` content. This gives agents a product overview and focused discovery links without treating every application route as documentation.
93
+
92
94
  Geistdocs does not infer Markdown mappings for `content` sections with `route: "/"`. A root catch-all such as `/*path` can make a homepage or other application routes look like documentation. Use explicit `markdownRoutes` for root-mounted docs.
93
95
 
94
96
  ```tsx title="lib/geistdocs/config.tsx"
@@ -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.23.0",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -34,10 +34,18 @@
34
34
  "types": "./dist/layout.d.ts",
35
35
  "default": "./dist/layout.js"
36
36
  },
37
+ "./localize-href": {
38
+ "types": "./dist/localize-href.d.ts",
39
+ "default": "./dist/localize-href.js"
40
+ },
37
41
  "./navbar": {
38
42
  "types": "./dist/navbar.d.ts",
39
43
  "default": "./dist/navbar.js"
40
44
  },
45
+ "./page-visibility": {
46
+ "types": "./dist/page-visibility.d.ts",
47
+ "default": "./dist/page-visibility.js"
48
+ },
41
49
  "./footer": {
42
50
  "types": "./dist/footer.d.ts",
43
51
  "default": "./dist/footer.js"
@@ -94,6 +102,10 @@
94
102
  "types": "./dist/routes/mcp.d.ts",
95
103
  "default": "./dist/routes/mcp.js"
96
104
  },
105
+ "./routes/not-found": {
106
+ "types": "./dist/routes/not-found.d.ts",
107
+ "default": "./dist/routes/not-found.js"
108
+ },
97
109
  "./proxy": {
98
110
  "types": "./dist/proxy.d.ts",
99
111
  "default": "./dist/proxy.js"
@@ -262,7 +274,7 @@
262
274
  "@orama/tokenizers": "^3.1.16",
263
275
  "@streamdown/cjk": "^1.0.1",
264
276
  "@streamdown/code": "^1.0.1",
265
- "@vercel/agent-readability": "^0.5.1",
277
+ "@vercel/agent-readability": "^0.6.0",
266
278
  "@vercel/oidc": "^3.4.1",
267
279
  "ai": "^6.0.132",
268
280
  "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.
@@ -4,17 +4,31 @@ interface TextGridSectionProps {
4
4
  title: string;
5
5
  description: string;
6
6
  }[];
7
+ description: string;
8
+ title: string;
7
9
  }
8
10
 
9
- export const TextGridSection = ({ data }: TextGridSectionProps) => (
10
- <div className="grid @min-[768px]:grid-cols-4 gap-8 @min-[640px]:py-12 py-8">
11
- {data.map((item) => (
12
- <div key={item.id}>
13
- <h3 className="mb-2 font-[450] text-gray-1000 text-heading-20 tracking-tight">
14
- {item.title}
15
- </h3>
16
- <p className="text-copy-16 text-gray-900">{item.description}</p>
17
- </div>
18
- ))}
19
- </div>
11
+ export const TextGridSection = ({
12
+ data,
13
+ description,
14
+ title,
15
+ }: TextGridSectionProps) => (
16
+ <section className="grid gap-8 @min-[640px]:py-12 py-8">
17
+ <div className="grid max-w-3xl gap-2 text-balance">
18
+ <h2 className="font-[450]! @min-[1024px]:text-[40px] @min-[640px]:text-2xl @min-[768px]:text-3xl text-gray-1000 text-xl tracking-tighter">
19
+ {title}
20
+ </h2>
21
+ <p className="text-gray-900 text-lg">{description}</p>
22
+ </div>
23
+ <div className="grid @min-[768px]:grid-cols-4 gap-8">
24
+ {data.map((item) => (
25
+ <div key={item.id}>
26
+ <h3 className="mb-2 font-[450] text-gray-1000 text-heading-20 tracking-tight">
27
+ {item.title}
28
+ </h3>
29
+ <p className="text-copy-16 text-gray-900">{item.description}</p>
30
+ </div>
31
+ ))}
32
+ </div>
33
+ </section>
20
34
  );
@@ -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]}>