@vercel/geistdocs 1.21.0 → 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.
- package/dist/cli/index.js +1 -1
- package/dist/footer.js +1 -1
- package/dist/internal/chat/copy-chat.d.ts.map +1 -1
- package/dist/internal/chat/copy-chat.js +1 -1
- package/dist/internal/chat/shell.d.ts.map +1 -1
- package/dist/internal/chat/shell.js +8 -3
- package/dist/internal/docs-page-error-boundary.d.ts +10 -0
- package/dist/internal/docs-page-error-boundary.d.ts.map +1 -0
- package/dist/internal/docs-page-error-boundary.js +7 -0
- package/dist/internal/localized-link.js +1 -1
- package/dist/internal/navbar/navbar-logo.d.ts.map +1 -1
- package/dist/internal/navbar/navbar-logo.js +2 -2
- package/dist/internal/page-breadcrumb.d.ts.map +1 -1
- package/dist/internal/page-breadcrumb.js +1 -1
- package/dist/internal/page-footer.d.ts.map +1 -1
- package/dist/internal/page-footer.js +2 -2
- package/dist/internal/search.d.ts.map +1 -1
- package/dist/internal/sidebar.d.ts.map +1 -1
- package/dist/internal/sidebar.js +14 -8
- package/dist/pages/docs.d.ts +1 -1
- package/dist/pages/docs.d.ts.map +1 -1
- package/dist/pages/docs.js +6 -2
- package/dist/proxy.d.ts.map +1 -1
- package/dist/proxy.js +2 -8
- package/dist/routes/llms.d.ts +5 -2
- package/dist/routes/llms.d.ts.map +1 -1
- package/dist/routes/llms.js +8 -10
- package/docs/agents.md +1 -1
- package/docs/llms.txt +69 -16
- package/docs/manifest.json +1 -1
- package/docs/pages/agent-readiness.md +2 -2
- package/docs/pages/configuration.md +6 -0
- package/docs/pages/llms-txt.md +3 -3
- package/docs/pages/md.md +3 -3
- package/docs/pages/migration.md +49 -5
- package/docs/pages/provider.md +2 -0
- package/docs/pages/versioned-docs.md +3 -2
- package/package.json +4 -4
- package/template/AGENTS.md +3 -0
- package/template/app/[lang]/(home)/layout.tsx +3 -2
- package/template/app/[lang]/.well-known/mcp.json/route.ts +3 -5
- package/template/app/[lang]/agents.md/route.ts +1 -1
- package/template/app/[lang]/docs/layout.tsx +3 -2
- package/template/app/[lang]/layout.tsx +7 -2
- package/template/app/[lang]/llms.mdx/[[...slug]]/route.ts +4 -5
- package/template/app/[lang]/llms.txt/route.ts +1 -1
- package/template/app/[lang]/rss.xml/route.ts +14 -7
- package/template/app/[lang]/sitemap.md/route.ts +4 -5
- package/template/app/sitemap.ts +5 -2
- package/template/content/docs/agent-readiness.mdx +2 -2
- package/template/content/docs/configuration.mdx +6 -0
- package/template/content/docs/llms-txt.cn.mdx +2 -2
- package/template/content/docs/llms-txt.mdx +3 -3
- package/template/content/docs/md.mdx +3 -3
- package/template/content/docs/migration.mdx +49 -5
- package/template/content/docs/provider.cn.mdx +2 -0
- package/template/content/docs/provider.mdx +2 -0
- package/template/content/docs/versioned-docs.mdx +3 -2
- package/template/lib/geistdocs/root-params.ts +5 -0
- package/template/next.config.ts +2 -4
- package/template/package.json +3 -3
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
1893
|
-
const
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
3279
|
+
export const { GET } = createLlmsRoute({
|
|
3227
3280
|
source: geistdocsSource,
|
|
3228
3281
|
filterPage: (page) => !page.url.includes("/internal"),
|
|
3229
3282
|
});
|
package/docs/manifest.json
CHANGED
|
@@ -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
|
|
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
|
|
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/llms-txt.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
package/docs/pages/migration.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
269
|
+
export const { GET, generateStaticParams } = createMcpManifestRoute({
|
|
226
270
|
config,
|
|
227
271
|
});
|
|
228
272
|
```
|
package/docs/pages/provider.md
CHANGED
|
@@ -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
|
|
238
|
-
const
|
|
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.
|
|
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.
|
|
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",
|
|
@@ -296,7 +296,7 @@
|
|
|
296
296
|
"zod": "^4.1.13"
|
|
297
297
|
},
|
|
298
298
|
"peerDependencies": {
|
|
299
|
-
"next": "^16.
|
|
299
|
+
"next": "^16.3.0",
|
|
300
300
|
"react": "^19.2.3",
|
|
301
301
|
"react-dom": "^19.2.3",
|
|
302
302
|
"tailwindcss": "^4.1.17"
|
|
@@ -310,7 +310,7 @@
|
|
|
310
310
|
"@types/react": "^19.2.7",
|
|
311
311
|
"@types/react-dom": "^19.2.3",
|
|
312
312
|
"mdast-util-mdx-jsx": "^3.2.0",
|
|
313
|
-
"next": "16.
|
|
313
|
+
"next": "16.3.1",
|
|
314
314
|
"react": "^19.2.3",
|
|
315
315
|
"react-dom": "^19.2.3",
|
|
316
316
|
"tsup": "^8.5.1",
|
package/template/AGENTS.md
CHANGED
|
@@ -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
|
|
6
|
-
const
|
|
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
|
|
5
|
-
|
|
6
|
-
|
|
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
|
|
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
|
|
5
|
-
const
|
|
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
|
|
10
|
-
|
|
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
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
});
|
|
4
|
+
export const { GET, generateStaticParams } = createDocsMarkdownRoute({
|
|
5
|
+
notFound: {},
|
|
6
|
+
sources: [geistdocsSource],
|
|
7
|
+
});
|
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
});
|
|
5
|
+
export const { GET, generateStaticParams } = createSitemapMarkdownRoute({
|
|
6
|
+
config,
|
|
7
|
+
sources: [{ source: geistdocsSource }],
|
|
8
|
+
});
|
package/template/app/sitemap.ts
CHANGED
|
@@ -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
|
-
|
|
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 = [];
|