@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.
- package/dist/cli/index.js +1 -1
- package/dist/config.d.ts +2 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/footer.d.ts.map +1 -1
- package/dist/footer.js +5 -0
- package/dist/home-layout.d.ts +2 -2
- package/dist/home-layout.d.ts.map +1 -1
- package/dist/home-layout.js +52 -18
- 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 +2 -2
- package/dist/internal/navbar/navbar-logo.d.ts.map +1 -1
- package/dist/internal/navbar/navbar-logo.js +2 -2
- package/dist/internal/page-actions-client.d.ts.map +1 -1
- package/dist/internal/page-actions-client.js +18 -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/localize-href.d.ts +6 -0
- package/dist/localize-href.d.ts.map +1 -0
- package/dist/{internal/localize-href.js → localize-href.js} +2 -5
- package/dist/{internal/page-visibility.d.ts → page-visibility.d.ts} +1 -1
- package/dist/page-visibility.d.ts.map +1 -0
- package/dist/pages/docs.d.ts +3 -3
- package/dist/pages/docs.d.ts.map +1 -1
- package/dist/pages/docs.js +16 -7
- package/dist/proxy.d.ts +1 -1
- package/dist/proxy.d.ts.map +1 -1
- package/dist/proxy.js +15 -10
- package/dist/routes/agents.d.ts.map +1 -1
- package/dist/routes/agents.js +4 -4
- package/dist/routes/chat.js +1 -1
- package/dist/routes/llms.d.ts +5 -2
- package/dist/routes/llms.d.ts.map +1 -1
- package/dist/routes/llms.js +9 -11
- package/dist/routes/not-found.d.ts +14 -0
- package/dist/routes/not-found.d.ts.map +1 -0
- package/dist/routes/not-found.js +74 -0
- package/dist/routes/search.js +1 -1
- package/dist/routes/sitemap.d.ts +1 -1
- package/dist/routes/sitemap.d.ts.map +1 -1
- package/dist/routes/sitemap.js +1 -1
- package/docs/agents.md +1 -1
- package/docs/llms.txt +76 -19
- package/docs/manifest.json +1 -1
- package/docs/pages/agent-readiness.md +3 -3
- package/docs/pages/configuration.md +6 -0
- package/docs/pages/env.md +2 -2
- package/docs/pages/llms-txt.md +3 -3
- package/docs/pages/md.md +5 -3
- package/docs/pages/migration.md +49 -5
- package/docs/pages/provider.md +2 -0
- package/docs/pages/proxy.md +2 -0
- package/docs/pages/versioned-docs.md +3 -2
- package/package.json +14 -2
- package/template/AGENTS.md +3 -0
- package/template/app/[lang]/(home)/components/text-grid-section.tsx +25 -11
- package/template/app/[lang]/(home)/layout.tsx +3 -2
- package/template/app/[lang]/(home)/opengraph-image.tsx +40 -0
- package/template/app/[lang]/(home)/page.tsx +143 -89
- package/template/app/[lang]/.well-known/mcp.json/route.ts +3 -5
- package/template/app/[lang]/[...not-found]/route.ts +4 -0
- 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 +14 -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]/not-found.tsx +37 -0
- package/template/app/[lang]/rss.xml/route.ts +17 -11
- package/template/app/[lang]/sitemap.md/route.ts +4 -5
- package/template/app/robots.ts +4 -4
- package/template/app/sitemap.ts +16 -10
- package/template/content/docs/agent-readiness.mdx +3 -3
- package/template/content/docs/configuration.mdx +6 -0
- package/template/content/docs/env.mdx +2 -2
- 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 +5 -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/proxy.mdx +2 -0
- package/template/content/docs/versioned-docs.mdx +3 -2
- package/template/lib/geistdocs/config.tsx +2 -0
- package/template/lib/geistdocs/public-path.ts +14 -0
- package/template/lib/geistdocs/root-params.ts +5 -0
- package/template/lib/geistdocs/site-url-warning.ts +10 -0
- package/template/lib/geistdocs/site-url.ts +33 -0
- package/template/next.config.ts +2 -10
- package/template/package.json +2 -2
- package/dist/internal/localize-href.d.ts +0 -9
- package/dist/internal/localize-href.d.ts.map +0 -1
- package/dist/internal/page-visibility.d.ts.map +0 -1
- package/template/app/[lang]/(home)/components/templates.tsx +0 -48
- /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.
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
|
@@ -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
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
3283
|
+
export const { GET } = createLlmsRoute({
|
|
3227
3284
|
source: geistdocsSource,
|
|
3228
3285
|
filterPage: (page) => !page.url.includes("/internal"),
|
|
3229
3286
|
});
|
package/docs/manifest.json
CHANGED
|
@@ -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
|
|
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/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.
|
|
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
|
-
|
|
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.
|
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,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
|
|
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
|
-
|
|
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
|
|
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:
|
package/docs/pages/proxy.md
CHANGED
|
@@ -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
|
|
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.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.
|
|
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",
|
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.
|
|
@@ -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 = ({
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
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
|
|
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]}>
|