@vercel/geistdocs 1.3.1 → 1.4.1

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 (48) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +6 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/routes/agents.d.ts.map +1 -1
  5. package/dist/routes/agents.js +14 -29
  6. package/dist/routes/discovery.d.ts +14 -0
  7. package/dist/routes/discovery.d.ts.map +1 -0
  8. package/dist/routes/discovery.js +74 -0
  9. package/dist/routes/mcp.d.ts +26 -0
  10. package/dist/routes/mcp.d.ts.map +1 -0
  11. package/dist/routes/mcp.js +31 -0
  12. package/dist/source.d.ts +1 -1
  13. package/dist/source.d.ts.map +1 -1
  14. package/dist/source.js +4 -1
  15. package/docs/agents.md +44 -0
  16. package/docs/llms.txt +2965 -0
  17. package/docs/manifest.json +194 -0
  18. package/docs/pages/agent-readiness.md +141 -0
  19. package/docs/pages/ask-ai.md +143 -0
  20. package/docs/pages/configuration.md +278 -0
  21. package/docs/pages/deployment.md +53 -0
  22. package/docs/pages/edit-on-github.md +53 -0
  23. package/docs/pages/env.md +62 -0
  24. package/docs/pages/feedback.md +91 -0
  25. package/docs/pages/getting-started.md +116 -0
  26. package/docs/pages/index.md +99 -0
  27. package/docs/pages/internationalization.md +124 -0
  28. package/docs/pages/llms-txt.md +88 -0
  29. package/docs/pages/md.md +84 -0
  30. package/docs/pages/migration.md +376 -0
  31. package/docs/pages/open-in-chat.md +82 -0
  32. package/docs/pages/provider.md +76 -0
  33. package/docs/pages/proxy.md +180 -0
  34. package/docs/pages/rss.md +110 -0
  35. package/docs/pages/syntax.md +413 -0
  36. package/docs/pages/theme-aware-image.md +59 -0
  37. package/docs/pages/versioned-docs.md +230 -0
  38. package/docs/sitemap.md +25 -0
  39. package/package.json +12 -2
  40. package/styles.css +174 -0
  41. package/template/AGENTS.md +10 -3
  42. package/template/app/[lang]/.well-known/mcp.json/route.ts +8 -0
  43. package/template/content/docs/agent-readiness.mdx +44 -8
  44. package/template/content/docs/configuration.mdx +1 -0
  45. package/template/content/docs/index.mdx +1 -1
  46. package/template/content/docs/llms-txt.mdx +1 -1
  47. package/template/content/docs/migration.mdx +12 -2
  48. package/template/package.json +1 -1
package/docs/llms.txt ADDED
@@ -0,0 +1,2965 @@
1
+ # Geistdocs Package Documentation
2
+
3
+ These docs are bundled with `@vercel/geistdocs` 1.4.1.
4
+ They describe how to build package-backed Geistdocs sites and how to use the package APIs from generated project adapters.
5
+
6
+ ## Documentation Index
7
+
8
+ - [Overview](pages/index.md): Geistdocs is a packaged documentation system for creating Next.js and Fumadocs sites with shared runtime features.
9
+ - [Getting Started](pages/getting-started.md): Create a Geistdocs project, run it locally, and edit your first documentation page.
10
+ - [Environment Variables](pages/env.md): Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
11
+ - [Deploy to Vercel](pages/deployment.md): Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
12
+ - [Migration guide](pages/migration.md): Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
13
+ - [Configuration](pages/configuration.md): Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
14
+ - [Syntax](pages/syntax.md): Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
15
+ - [Geistdocs Provider](pages/provider.md): The root provider component that wraps your application to handle toast notifications, search, and analytics.
16
+ - [Versioned docs](pages/versioned-docs.md): Use createVersionedSources to configure stable, pre-release, or host-based documentation versions.
17
+ - [Proxy and markdown routes](pages/proxy.md): Configure createProxy with before and after hooks, markdown route mappings, and a static Next.js matcher.
18
+ - [.md Extension](pages/md.md): Access any documentation page as raw Markdown by appending .md or .mdx to the URL for AI tool consumption.
19
+ - [Agent readiness](pages/agent-readiness.md): Generate /agents.md and /.well-known/mcp.json from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
20
+ - [Ask AI](pages/ask-ai.md): An AI-powered chat assistant with context-aware search, persistent history, and suggested prompts for your documentation.
21
+ - [Edit on GitHub](pages/edit-on-github.md): A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
22
+ - [Feedback](pages/feedback.md): An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
23
+ - [Internationalization](pages/internationalization.md): Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
24
+ - [llms.txt](pages/llms-txt.md): A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
25
+ - [Open in Chat](pages/open-in-chat.md): Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
26
+ - [RSS](pages/rss.md): An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
27
+ - [Theme-Aware Image](pages/theme-aware-image.md): A component that swaps images based on the active theme, built on top of Next.js Image.
28
+
29
+ ---
30
+
31
+ ---
32
+ title: Overview
33
+ description: Learn how Geistdocs packages the CLI, runtime, and template for documentation sites
34
+ type: overview
35
+ summary: Geistdocs is a packaged documentation system for creating Next.js and Fumadocs sites with shared runtime features.
36
+ url: /docs
37
+ source: apps/template/content/docs/index.mdx
38
+ related:
39
+ - /docs/getting-started
40
+ - /docs/migration
41
+ - /docs/configuration
42
+ ---
43
+
44
+ # Overview
45
+
46
+ Geistdocs is a packaged documentation system built with Next.js, Fumadocs, and shared Vercel documentation patterns. Use it to create a docs site with local content files and package-managed runtime features.
47
+
48
+ Help me understand this Geistdocs project. Explain how the `@vercel/geistdocs` package, local adapter files, and `content/docs` folder work together, then suggest the first files I should edit for my documentation site.
49
+
50
+ ## How Geistdocs works
51
+
52
+ Geistdocs has three main parts:
53
+
54
+ - `@vercel/geistdocs`: The npm package that provides the CLI, runtime components, route helpers, MDX components, page actions, and bundled template.
55
+ - Local adapter files: The files in your generated project that connect your configuration, content source, routes, and UI customization to the package.
56
+ - Platform services: Hosted endpoints at `geistdocs.com` for optional translation, feedback, and markdown tracking features.
57
+
58
+ ```mermaid
59
+ flowchart TB
60
+ subgraph Package["@vercel/geistdocs package"]
61
+ cli["CLI: init, update, translate"]
62
+ runtime["Runtime: layout, routes, MDX, controls"]
63
+ bundledTemplate["Bundled template snapshot"]
64
+ end
65
+
66
+ subgraph Site["Generated docs site"]
67
+ config["geistdocs.tsx"]
68
+ adapters["app/, components/geistdocs/, lib/geistdocs/"]
69
+ content["content/docs/*.mdx"]
70
+ end
71
+
72
+ subgraph Platform["Geistdocs platform"]
73
+ translate["/translate"]
74
+ feedback["/feedback"]
75
+ tracking["/md-tracking"]
76
+ end
77
+
78
+ cli --> bundledTemplate
79
+ bundledTemplate --> Site
80
+ adapters --> runtime
81
+ content --> adapters
82
+ cli --> translate
83
+ runtime --> feedback
84
+ runtime --> tracking
85
+ ```
86
+
87
+ ## What you edit
88
+
89
+ Most projects start by editing these files:
90
+
91
+ - `content/docs`: Write and organize your docs.
92
+ - `content/docs/meta.json`: Control sidebar order and groups.
93
+ - `geistdocs.tsx`: Configure the logo, nav, GitHub repo, title, AI prompt, translations, and feature flags.
94
+ - `components/geistdocs/mdx-components.tsx`: Add or override MDX components.
95
+ - `app/[lang]/docs/[[...slug]]/page.tsx`: Configure docs page behavior, such as custom render hooks.
96
+ - `proxy.ts`: Add site-specific request logic before or after package-managed markdown negotiation.
97
+
98
+ ## What the package owns
99
+
100
+ The package owns shared behavior such as docs rendering, page actions, search, Ask AI, markdown routes, `llms.txt`, and reusable MDX components. Updating `@vercel/geistdocs` gives your project package-level fixes and features without overwriting user-owned adapter files.
101
+
102
+ Ask AI uses AI SDK v6 through package-managed client and server code. Generated projects include `ai` v6 and `@ai-sdk/react` v3 so the package chat UI and `createChatRoute` use the supported AI SDK APIs.
103
+
104
+ Advanced projects can use package APIs for versioned docs, multiple content sources, custom page metadata, and custom proxy hooks while keeping runtime behavior in `@vercel/geistdocs`.
105
+
106
+ ## Included features
107
+
108
+ - MDX documentation with custom components
109
+ - Local content in `content/docs`
110
+ - Search and Ask AI
111
+ - Page actions, including feedback, copy page, open in chat, and edit on GitHub
112
+ - Agent-readiness metadata with `/agents.md` and `/.well-known/mcp.json`
113
+ - Raw Markdown routes for AI tools
114
+ - `llms.txt`
115
+ - Versioned docs and multiple content sources
116
+ - Proxy hooks for custom request logic
117
+ - RSS feed
118
+ - Theme-aware images
119
+ - Internationalized routes
120
+ - CLI commands for init, update, and translation
121
+
122
+ ## Next steps
123
+
124
+ - Follow [Getting Started](/docs/getting-started) to create and run a project.
125
+ - Read [Migration guide](/docs/migration) to move an existing docs site to package-backed Geistdocs.
126
+ - Read [Configuration](/docs/configuration) to customize the generated site.
127
+ - Read [Versioned docs](/docs/versioned-docs) to configure multiple docs versions.
128
+ - Read [Proxy and markdown routes](/docs/proxy) to add custom request logic.
129
+ - Read [Syntax](/docs/syntax) to write content with MDX components.
130
+
131
+
132
+ ---
133
+
134
+ ---
135
+ title: Getting Started
136
+ description: Create a Geistdocs project and start writing documentation
137
+ type: guide
138
+ summary: Create a Geistdocs project, run it locally, and edit your first documentation page.
139
+ url: /docs/getting-started
140
+ source: apps/template/content/docs/getting-started.mdx
141
+ related:
142
+ - /docs/configuration
143
+ - /docs/migration
144
+ - /docs/syntax
145
+ - /docs/deployment
146
+ ---
147
+
148
+ # Getting Started
149
+
150
+ Create a Geistdocs site with the package CLI, then edit the generated content and configuration files. If you already have a Fumadocs or custom Geist docs site, read [Migration guide](/docs/migration) before moving route adapters and middleware behavior.
151
+
152
+ Create a Geistdocs project with `pnpm dlx @vercel/geistdocs init --name my-docs`. Then open `my-docs`, run `pnpm dev`, and explain which files I should edit first: `geistdocs.tsx`, `content/docs`, `content/docs/meta.json`, and `components/geistdocs/mdx-components.tsx`.
153
+
154
+ ## Prerequisites
155
+
156
+ Before you begin, install:
157
+
158
+ - Node.js 18 or later
159
+ - pnpm, npm, or another package manager
160
+ - Git
161
+
162
+ ## Create a project
163
+
164
+ Run the Geistdocs CLI from an empty parent folder:
165
+
166
+ ```bash title="Terminal"
167
+ pnpm dlx @vercel/geistdocs init --name my-docs
168
+ ```
169
+
170
+ You can also use npm:
171
+
172
+ ```bash title="Terminal"
173
+ npx @vercel/geistdocs init --name my-docs
174
+ ```
175
+
176
+ The CLI copies the template bundled in the package, rewrites the generated app to depend on the same `@vercel/geistdocs` version, installs dependencies, copies `.env.example` to `.env.local`, and initializes Git.
177
+
178
+ ## Understand generated dependencies
179
+
180
+ Generated projects include `@vercel/geistdocs`, `ai` v6, and `@ai-sdk/react` v3. Geistdocs uses those AI SDK packages for Ask AI, including the chat client transport and `createChatRoute` server behavior.
181
+
182
+ Update Ask AI by updating `@vercel/geistdocs`, not by copying package chat internals into the app. If your project uses the AI SDK directly for separate product features, keep that code compatible with the app's installed AI SDK version; package-owned Ask AI does not need to match another consumer project's `ai` version.
183
+
184
+ ## Start the development server
185
+
186
+ Open the generated project and start Next.js:
187
+
188
+ ```bash title="Terminal"
189
+ cd my-docs
190
+ pnpm dev
191
+ ```
192
+
193
+ Open `http://localhost:3000` in your browser.
194
+
195
+ ## Edit your first page
196
+
197
+ Docs live in `content/docs`. Edit the overview page:
198
+
199
+ ```mdx title="content/docs/index.mdx"
200
+ ---
201
+ title: Overview
202
+ description: Learn how to use my project.
203
+ ---
204
+
205
+ My project helps developers build with clear documentation.
206
+
207
+ ## Start here
208
+
209
+ Add the first workflow you want readers to complete.
210
+ ```
211
+
212
+ Add more pages by creating new `.mdx` files in `content/docs`.
213
+
214
+ ## Update the sidebar
215
+
216
+ Use `content/docs/meta.json` to control page order and groups:
217
+
218
+ ```json title="content/docs/meta.json"
219
+ {
220
+ "title": "Documentation",
221
+ "root": true,
222
+ "pages": ["index", "getting-started", "---Guides---", "deploy"]
223
+ }
224
+ ```
225
+
226
+ ## Configure the site
227
+
228
+ Use `geistdocs.tsx` to customize the site shell:
229
+
230
+ ```tsx title="geistdocs.tsx"
231
+ export const title = "My Documentation";
232
+
233
+ export const nav = [
234
+ { label: "Docs", href: "/docs" },
235
+ { label: "GitHub", href: "https://github.com/my-org/my-repo" },
236
+ ];
237
+ ```
238
+
239
+ Read [Configuration](/docs/configuration) for the full configuration surface.
240
+
241
+ ## Update Geistdocs
242
+
243
+ For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files.
244
+
245
+ ```bash title="Terminal"
246
+ pnpm exec geistdocs update
247
+ ```
248
+
249
+ Review and test dependency changes before committing.
250
+
251
+
252
+ ---
253
+
254
+ ---
255
+ title: Environment Variables
256
+ description: Learn about the environment variables used in Geistdocs
257
+ type: reference
258
+ summary: Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
259
+ url: /docs/env
260
+ source: apps/template/content/docs/env.mdx
261
+ prerequisites:
262
+ - /docs/getting-started
263
+ related:
264
+ - /docs/configuration
265
+ - /docs/deployment
266
+ ---
267
+
268
+ # Environment Variables
269
+
270
+ Geistdocs uses environment variables to configure Ask AI, optional Vertex-backed proxy mode, and production URL behavior.
271
+
272
+ Review this Geistdocs project and help me configure the required environment variables. Check whether `AI_GATEWAY_API_KEY`, `GEISTDOCS_CHAT_PROXY_URL`, and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` are needed for the features I enabled, then tell me where to set them locally and on Vercel.
273
+
274
+ ## `AI_GATEWAY_API_KEY`
275
+
276
+ The API key for the AI Gateway. This is used to power the default local AI chat functionality when `GEISTDOCS_CHAT_PROXY_URL` is not set.
277
+
278
+ > This is automatically set when deploying to Vercel.
279
+
280
+ Leave `GEISTDOCS_CHAT_PROXY_URL` unset to use AI Gateway mode.
281
+
282
+ ## `GEISTDOCS_CHAT_PROXY_URL`
283
+
284
+ An optional URL for a chat proxy. When set, Geistdocs searches the local documentation on the first user message, injects the current page and related docs as context, and forwards the request to this proxy.
285
+
286
+ Use this when routing Ask AI through a central Vertex-backed service. The value should point at the Geistdocs platform proxy and include `/vertex`:
287
+
288
+ ```txt
289
+ https://<geistdocs-platform-deployment>/vertex
290
+ ```
291
+
292
+ When this variable is set, the site does not need `AI_GATEWAY_API_KEY` for Ask AI requests. The platform proxy calls Vertex and forwards a Vercel OIDC token in `x-vercel-trusted-oidc-idp-token` so the Vertex deployment can validate the caller through Deployment Protection Trusted Sources.
293
+
294
+ ## `GEISTDOCS_CHAT_PROXY_TOKEN`
295
+
296
+ An optional bearer token for the chat proxy. Only set this if your proxy requires an `Authorization` header.
297
+
298
+ The default Geistdocs platform `/vertex` proxy uses Vercel OIDC and Trusted Sources, so it does not require this token.
299
+
300
+ ## Vertex-backed proxy setup
301
+
302
+ To route Ask AI through Vertex:
303
+
304
+ 1. Use or deploy the central Geistdocs platform proxy with its `/vertex` route.
305
+ 2. In the Vertex deployment's Deployment Protection settings, add the Geistdocs platform Vercel project as a Trusted Source.
306
+ 3. In each Geistdocs site that should use Vertex, set `GEISTDOCS_CHAT_PROXY_URL` to the platform proxy URL, including `/vertex`.
307
+ 4. Leave `GEISTDOCS_CHAT_PROXY_TOKEN` unset unless you replace the platform proxy with a custom bearer-authenticated proxy.
308
+
309
+ The Vertex deployment does not need a Geistdocs-specific environment variable. Access is controlled by Trusted Sources and the OIDC token forwarded by the platform proxy.
310
+
311
+ ## `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`
312
+
313
+ The production URL of the Geistdocs site. This is automatically set when deploying to Vercel.
314
+
315
+ 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.
316
+
317
+
318
+ ---
319
+
320
+ ---
321
+ title: Deploy to Vercel
322
+ description: Learn how to deploy your Geistdocs site to Vercel
323
+ type: guide
324
+ summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
325
+ url: /docs/deployment
326
+ source: apps/template/content/docs/deployment.mdx
327
+ prerequisites:
328
+ - /docs/getting-started
329
+ - /docs/env
330
+ related:
331
+ - /docs/configuration
332
+ ---
333
+
334
+ # Deploy to Vercel
335
+
336
+ Deploy a Geistdocs site to Vercel as a Next.js app. Make sure your package dependency, environment variables, and production URL are configured before shipping.
337
+
338
+ Help me deploy this Geistdocs project to Vercel. Check the package scripts, required environment variables, and Vercel project settings, then give me a deploy checklist for production.
339
+
340
+ ## Prerequisites
341
+
342
+ Before deploying, you need:
343
+
344
+ - A [GitHub account](https://github.com) with your Geistdocs repository
345
+ - A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
346
+ - Your Vercel account connected to your GitHub account
347
+ - Environment variables ready (see [Environment Variables](/docs/env))
348
+
349
+ ## Deploy to Vercel
350
+
351
+ To deploy from the Vercel dashboard:
352
+
353
+ 1. Go to [vercel.com/new](https://vercel.com/new)
354
+ 2. Select your Geistdocs repository
355
+ 3. Configure your project settings:
356
+ - **Framework Preset**: Next.js (automatically detected)
357
+ - **Build Command**: `pnpm build` or `npm run build`
358
+ - **Output Directory**: `.next` (default)
359
+ - **Install Command**: `pnpm install` or `npm install`
360
+ 4. Add your environment variables (see [Environment Variables](/docs/env))
361
+ 5. Click "Deploy"
362
+
363
+ ## Deploy with Vertex-backed Ask AI
364
+
365
+ If your site routes Ask AI through the central Vertex-backed proxy, configure both the Geistdocs site and the Vertex deployment before testing production chat.
366
+
367
+ 1. Set `GEISTDOCS_CHAT_PROXY_URL` on the Geistdocs site to the platform proxy URL, including `/vertex`.
368
+ 2. Leave `GEISTDOCS_CHAT_PROXY_TOKEN` unset unless your proxy requires bearer authentication.
369
+ 3. Add the Geistdocs platform Vercel project as a Trusted Source in the Vertex deployment's Deployment Protection settings.
370
+ 4. Confirm the platform proxy can forward the Vercel OIDC token to Vertex in `x-vercel-trusted-oidc-idp-token`.
371
+
372
+ The Geistdocs site does not need Vertex credentials. The platform proxy authenticates to Vertex with Vercel OIDC and Trusted Sources.
373
+
374
+
375
+ ---
376
+
377
+ ---
378
+ title: Migration guide
379
+ description: Migrate a Fumadocs or custom Geist docs site to package-backed Geistdocs
380
+ type: guide
381
+ summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
382
+ url: /docs/migration
383
+ source: apps/template/content/docs/migration.mdx
384
+ prerequisites:
385
+ - /docs/configuration
386
+ - /docs/proxy
387
+ related:
388
+ - /docs/versioned-docs
389
+ - /docs/llms-txt
390
+ - /docs/agent-readiness
391
+ ---
392
+
393
+ # Migration guide
394
+
395
+ Migrate an existing Fumadocs or custom Geist documentation site to `@vercel/geistdocs` by moving shared behavior into package APIs and keeping site-specific adapters local. The safest migration keeps content, routing decisions, and product-specific UI in your app while replacing copied runtime code with thin package-backed adapters.
396
+
397
+ Help me migrate this existing docs site to package-backed Geistdocs. Inspect `source.config.ts`, `lib/geistdocs/source.ts`, app route files, `proxy.ts` or `middleware.ts`, `public/llms.txt`, Open Graph routes, Tailwind CSS setup, `package.json` AI SDK dependencies, and environment variables. Then produce a step-by-step migration plan using `@vercel/geistdocs` package APIs without copying package internals.
398
+
399
+ ## Before you migrate
400
+
401
+ Create a working branch and inventory the current site before replacing code:
402
+
403
+ - Existing Fumadocs collections in `source.config.ts`.
404
+ - Public route families, such as `/docs`, `/api-reference`, `/guides`, or `/`.
405
+ - Existing `middleware.ts` or `proxy.ts` behavior.
406
+ - Static files that overlap package routes, such as `public/llms.txt`.
407
+ - Search, chat, `llms.txt`, page-level Markdown, `sitemap.md`, `agents.md`, `/.well-known/mcp.json`, RSS, and Open Graph routes.
408
+ - Tailwind CSS version and custom plugins.
409
+ - Direct app usage of `ai` or `@ai-sdk/react` outside Geistdocs.
410
+ - Environment variables required by the homepage, docs routes, or API routes.
411
+
412
+ Run the current project before changing it:
413
+
414
+ ```bash title="Terminal"
415
+ pnpm install
416
+ pnpm build
417
+ ```
418
+
419
+ Fix unrelated build failures first. A migration is safer when the starting point is reproducible.
420
+
421
+ ## Install Geistdocs
422
+
423
+ Add `@vercel/geistdocs` and align the supported Fumadocs and Next.js dependencies for the package version you are adopting.
424
+
425
+ For an existing project, use your package manager directly:
426
+
427
+ ```bash title="Terminal"
428
+ pnpm add @vercel/geistdocs
429
+ ```
430
+
431
+ If you are starting from a generated Geistdocs project and moving content into it, use the CLI:
432
+
433
+ ```bash title="Terminal"
434
+ pnpm dlx @vercel/geistdocs init --name my-docs
435
+ ```
436
+
437
+ ## Align Ask AI dependencies
438
+
439
+ 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.
440
+
441
+ If the existing app imports `ai` or `@ai-sdk/react` for product-specific features, migrate that code separately. Keep Geistdocs route adapters package-backed, and do not copy package chat internals into the app to preserve older AI SDK behavior.
442
+
443
+ ## Update source config
444
+
445
+ Use the source-config-safe export from `@vercel/geistdocs/source-config` in `source.config.ts`. This file is evaluated by `fumadocs-mdx` during dependency installation and builds, so avoid importing runtime component entry points from it.
446
+
447
+ ```ts title="source.config.ts"
448
+ import {
449
+ defineGeistdocsSourceConfig,
450
+ geistdocsFrontmatterSchema,
451
+ geistdocsMetaSchema,
452
+ } from "@vercel/geistdocs/source-config";
453
+ import { defineDocs } from "fumadocs-mdx/config";
454
+
455
+ export const docs = defineDocs({
456
+ dir: "content/docs",
457
+ docs: {
458
+ schema: geistdocsFrontmatterSchema,
459
+ postprocess: {
460
+ includeProcessedMarkdown: true,
461
+ },
462
+ },
463
+ meta: {
464
+ schema: geistdocsMetaSchema,
465
+ },
466
+ });
467
+
468
+ export default defineGeistdocsSourceConfig();
469
+ ```
470
+
471
+ For multiple docs families, create one collection per directory and reuse `geistdocsFrontmatterSchema`.
472
+
473
+ ## Create the package config
474
+
475
+ Use `@vercel/geistdocs/config` to centralize site metadata and route families in `lib/geistdocs/config.tsx`.
476
+
477
+ ```tsx title="lib/geistdocs/config.tsx"
478
+ import { defineConfig } from "@vercel/geistdocs/config";
479
+ import { Logo, github, nav, prompt, suggestions, title } from "@/geistdocs";
480
+
481
+ export const config = defineConfig({
482
+ title,
483
+ defaultLanguage: "en",
484
+ logo: <Logo />,
485
+ github,
486
+ nav,
487
+ content: [{ id: "docs", label: "Docs", dir: "content/docs", route: "/docs" }],
488
+ ai: {
489
+ prompt,
490
+ suggestions,
491
+ },
492
+ });
493
+ ```
494
+
495
+ Set `content` to every public documentation route family. `createProxy` uses this metadata to infer standard Markdown mappings for non-root sections.
496
+
497
+ ## Connect Fumadocs sources
498
+
499
+ Wrap each Fumadocs collection with `createSource` in `lib/geistdocs/source.ts`.
500
+
501
+ ```ts title="lib/geistdocs/source.ts"
502
+ import { createSource } from "@vercel/geistdocs/source";
503
+ import { docs } from "@/.source/server";
504
+ import { config } from "./config";
505
+
506
+ export const geistdocsSource = createSource({
507
+ docs,
508
+ config,
509
+ id: "docs",
510
+ label: "Docs",
511
+ });
512
+
513
+ export const source = geistdocsSource.source;
514
+ ```
515
+
516
+ For root-mounted docs, set `baseUrl: "/"` and use explicit `markdownRoutes` in `proxy.ts`:
517
+
518
+ ```ts title="lib/geistdocs/source.ts"
519
+ export const geistdocsSource = createSource({
520
+ docs,
521
+ config,
522
+ baseUrl: "/",
523
+ });
524
+ ```
525
+
526
+ ## Add route adapters
527
+
528
+ Keep App Router files thin. Route files should call package helpers instead of copying package internals.
529
+
530
+ ```tsx title="app/[lang]/docs/[[...slug]]/page.tsx"
531
+ import { createDocsPage } from "@vercel/geistdocs/pages/docs";
532
+ import { config } from "@/lib/geistdocs/config";
533
+ import { geistdocsSource } from "@/lib/geistdocs/source";
534
+
535
+ const docsPage = createDocsPage({
536
+ config,
537
+ source: geistdocsSource,
538
+ openGraph: {
539
+ images: true,
540
+ },
541
+ });
542
+
543
+ export default docsPage.Page;
544
+ export const generateStaticParams = docsPage.generateStaticParams;
545
+ export const generateMetadata = docsPage.generateMetadata;
546
+ ```
547
+
548
+ Set `openGraph.images` to `true` only when your app includes the Geistdocs OG route. If you do not add the OG route, omit `openGraph` or override metadata to avoid broken `/og/...` references.
549
+
550
+ ## Add AI-readable routes
551
+
552
+ Add the package route helpers for machine-readable docs surfaces.
553
+
554
+ ```ts title="app/[lang]/llms.txt/route.ts"
555
+ import { createLlmsRoute } from "@vercel/geistdocs/routes/llms";
556
+ import { geistdocsSource } from "@/lib/geistdocs/source";
557
+
558
+ export const { GET, revalidate } = createLlmsRoute({
559
+ sources: [geistdocsSource],
560
+ });
561
+ ```
562
+
563
+ ```ts title="app/[lang]/llms.mdx/[[...slug]]/route.ts"
564
+ import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
565
+ import { geistdocsSource } from "@/lib/geistdocs/source";
566
+
567
+ export const { GET, generateStaticParams, revalidate } =
568
+ createDocsMarkdownRoute({
569
+ source: geistdocsSource,
570
+ });
571
+ ```
572
+
573
+ ```ts title="app/[lang]/sitemap.md/route.ts"
574
+ import { createSitemapMarkdownRoute } from "@vercel/geistdocs/routes/sitemap";
575
+ import { config } from "@/lib/geistdocs/config";
576
+ import { geistdocsSource } from "@/lib/geistdocs/source";
577
+
578
+ export const { GET, generateStaticParams, revalidate, dynamic } =
579
+ createSitemapMarkdownRoute({
580
+ config,
581
+ sources: [{ source: geistdocsSource.source }],
582
+ });
583
+ ```
584
+
585
+ ```ts title="app/[lang]/agents.md/route.ts"
586
+ import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
587
+ import { config } from "@/lib/geistdocs/config";
588
+
589
+ export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
590
+ config,
591
+ });
592
+ ```
593
+
594
+ ```ts title="app/[lang]/.well-known/mcp.json/route.ts"
595
+ import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
596
+ import { config } from "@/lib/geistdocs/config";
597
+
598
+ export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
599
+ config,
600
+ });
601
+ ```
602
+
603
+ Delete `public/llms.txt` after adding `createLlmsRoute`. Static files in `public` can mask App Router route behavior.
604
+
605
+ ## Add search and Ask AI routes
606
+
607
+ Use package route helpers for search and chat. Keep these files as adapters so `@vercel/geistdocs` can ship AI SDK compatibility fixes.
608
+
609
+ ```ts title="app/api/search/route.ts"
610
+ import { createSearchRoute } from "@vercel/geistdocs/routes/search";
611
+ import { config } from "@/lib/geistdocs/config";
612
+ import { geistdocsSource } from "@/lib/geistdocs/source";
613
+
614
+ export const GET = createSearchRoute({ config, sources: [geistdocsSource] });
615
+ ```
616
+
617
+ ```ts title="app/api/chat/route.ts"
618
+ import { createChatRoute } from "@vercel/geistdocs/routes/chat";
619
+ import { config } from "@/lib/geistdocs/config";
620
+ import { geistdocsSource } from "@/lib/geistdocs/source";
621
+
622
+ const chatProxyUrl = process.env.GEISTDOCS_CHAT_PROXY_URL;
623
+ const chatProxyToken = process.env.GEISTDOCS_CHAT_PROXY_TOKEN;
624
+
625
+ export const { POST, maxDuration } = createChatRoute({
626
+ config,
627
+ proxy: chatProxyUrl
628
+ ? {
629
+ url: chatProxyUrl,
630
+ headers: chatProxyToken
631
+ ? { Authorization: `Bearer ${chatProxyToken}` }
632
+ : undefined,
633
+ }
634
+ : undefined,
635
+ sources: [geistdocsSource],
636
+ });
637
+ ```
638
+
639
+ Leave `GEISTDOCS_CHAT_PROXY_URL` unset for default AI Gateway mode. Set it to a `/vertex` proxy URL only when Ask AI should route model requests through the central Vertex-backed service.
640
+
641
+ ## Migrate middleware behavior
642
+
643
+ Use `createProxy` in `proxy.ts`. Put existing `middleware.ts` behavior in `before` or `after` hooks instead of replacing Geistdocs markdown negotiation.
644
+
645
+ ```ts title="proxy.ts"
646
+ import { createProxy } from "@vercel/geistdocs/proxy";
647
+ import { NextResponse } from "next/server";
648
+ import { config as geistdocsConfig } from "@/lib/geistdocs/config";
649
+
650
+ const proxy = createProxy({
651
+ config: geistdocsConfig,
652
+ before: async ({ request }) => {
653
+ if (request.nextUrl.pathname === "/legacy-docs") {
654
+ return NextResponse.redirect(new URL("/docs", request.url));
655
+ }
656
+
657
+ return null;
658
+ },
659
+ });
660
+
661
+ export const config = {
662
+ matcher: [
663
+ "/((?!api(?:/|$)|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
664
+ ],
665
+ };
666
+
667
+ export default proxy;
668
+ ```
669
+
670
+ Use `api(?:/|$)` in the matcher. A broad `api` exclusion also excludes routes such as `/api-reference`.
671
+
672
+ ## Configure Markdown route mappings
673
+
674
+ For standard non-root sections, `createProxy` can infer Markdown routes from `config.content`.
675
+
676
+ Use explicit `markdownRoutes` when the public docs URL does not map directly to the Markdown route handler:
677
+
678
+ ```ts title="proxy.ts"
679
+ const proxy = createProxy({
680
+ config: geistdocsConfig,
681
+ markdownRoutes: [
682
+ { from: "/docs/*path", to: "/[lang]/llms.mdx/*path" },
683
+ { from: "/api-reference/*path", to: "/[lang]/llms.mdx/api-reference/*path" },
684
+ ],
685
+ });
686
+ ```
687
+
688
+ Root-mounted docs need explicit mappings. If a homepage or app routes also live at `/`, do not use a broad `/*path` mapping. Map each docs family separately:
689
+
690
+ ```ts title="proxy.ts"
691
+ const proxy = createProxy({
692
+ config: geistdocsConfig,
693
+ markdownRoutes: [
694
+ { from: "/guides/*path", to: "/[lang]/llms.mdx/guides/*path" },
695
+ { from: "/api-reference/*path", to: "/[lang]/llms.mdx/api-reference/*path" },
696
+ ],
697
+ });
698
+ ```
699
+
700
+ ## Configure Tailwind CSS
701
+
702
+ Tailwind CSS v4 requires `@source` entries for package components and related dependencies.
703
+
704
+ ```css title="app/styles/geistdocs.css"
705
+ @import "tailwindcss";
706
+ @import "fumadocs-ui/css/shadcn.css";
707
+ @import "fumadocs-ui/css/preset.css";
708
+ @import "tw-animate-css";
709
+
710
+ @source "../../node_modules/@vercel/geistdocs/dist/**/*.js";
711
+ @source "../../node_modules/streamdown/dist/*.js";
712
+ ```
713
+
714
+ Move Tailwind CSS v3 plugin utilities into CSS-first v4 utilities or theme variables. Keep custom token names stable while you migrate components.
715
+
716
+ ## Handle environment variables
717
+
718
+ Do not require production secrets for local migration builds. If a homepage or API route depends on a production-only secret, add a local fallback or disable that integration in development.
719
+
720
+ ```ts title="lib/example-secret.ts"
721
+ export const flagsSecret =
722
+ process.env.FLAGS_SECRET ??
723
+ (process.env.NODE_ENV === "development" ? "local-development-secret" : undefined);
724
+ ```
725
+
726
+ Keep real secrets in `.env.local` and out of Git.
727
+
728
+ ## Verify the migration
729
+
730
+ Run the same checks after each routing or source change:
731
+
732
+ ```bash title="Terminal"
733
+ pnpm postinstall
734
+ pnpm build
735
+ pnpm dev
736
+ ```
737
+
738
+ Check these URLs locally:
739
+
740
+ - `/docs` or the migrated docs root.
741
+ - `/llms.txt`.
742
+ - `/sitemap.md`.
743
+ - `/agents.md`.
744
+ - `/.well-known/mcp.json` if `agent.mcp.servers` is configured.
745
+ - A page-level Markdown URL such as `/docs/getting-started.mdx`.
746
+ - A non-docs route that should not be rewritten as Markdown, such as the homepage.
747
+
748
+ ## Next steps
749
+
750
+ - Read [Configuration](/docs/configuration) to review package config options.
751
+ - Read [Proxy and markdown routes](/docs/proxy) to tune request handling.
752
+ - Read [Agent readiness](/docs/agent-readiness) to configure `/agents.md` and `/.well-known/mcp.json` for AI agents.
753
+
754
+
755
+ ---
756
+
757
+ ---
758
+ title: Configuration
759
+ description: Configure a Geistdocs site through local adapter files and package APIs
760
+ type: reference
761
+ summary: Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
762
+ url: /docs/configuration
763
+ source: apps/template/content/docs/configuration.mdx
764
+ prerequisites:
765
+ - /docs/getting-started
766
+ related:
767
+ - /docs/migration
768
+ - /docs/provider
769
+ - /docs/env
770
+ - /docs/versioned-docs
771
+ - /docs/proxy
772
+ ---
773
+
774
+ # Configuration
775
+
776
+ Configure Geistdocs through user-owned files in the generated project. Runtime features come from `@vercel/geistdocs`, while your local files control content, branding, routing adapters, and opt-in customization.
777
+
778
+ Review this Geistdocs project configuration. Explain what each export in `geistdocs.tsx` does, identify which features are enabled, and suggest safe customizations that do not require editing package internals.
779
+
780
+ ## Configuration files
781
+
782
+ | File | Purpose |
783
+ | --- | --- |
784
+ | `geistdocs.tsx` | Site-level settings, including logo, nav, GitHub repo, AI prompt, agent-readiness metadata, translations, and feature flags. |
785
+ | `source.config.ts` | Configures Fumadocs collections with the package-provided schema, Markdown plugins, and syntax theme. |
786
+ | `lib/geistdocs/config.tsx` | Converts `geistdocs.tsx` exports into the package config using `defineConfig`. |
787
+ | `source.config.ts` | Configures Fumadocs collections with package-safe schemas and Markdown processing. |
788
+ | `lib/geistdocs/source.ts` | Connects Fumadocs content collections to the package source adapter. |
789
+ | `components/geistdocs/mdx-components.tsx` | Adds or overrides MDX components. |
790
+ | `components/geistdocs/docs-layout.tsx` | Customizes the package-backed docs layout, including optional sidebar content. |
791
+ | `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
792
+ | `app/[lang]/agents.md/route.ts` | Configures the agent-readiness entry point. |
793
+ | `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery. |
794
+ | `app/[lang]/llms.txt/route.ts` | Configures the all-docs Markdown endpoint. |
795
+ | `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses. |
796
+ | `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
797
+ | `content/docs/meta.json` | Controls sidebar order and section labels. |
798
+
799
+ ## `geistdocs.tsx`
800
+
801
+ The root `geistdocs.tsx` file is the primary configuration surface:
802
+
803
+ ```tsx title="geistdocs.tsx"
804
+ export const Logo = () => <span>My Docs</span>;
805
+
806
+ export const github = {
807
+ owner: "my-org",
808
+ repo: "my-repo",
809
+ branch: "main",
810
+ editPath: "content/docs/{path}",
811
+ };
812
+
813
+ export const nav = [
814
+ { label: "Docs", href: "/docs" },
815
+ { label: "GitHub", href: "https://github.com/my-org/my-repo" },
816
+ ];
817
+
818
+ export const title = "My Documentation";
819
+
820
+ export const prompt =
821
+ "You are a helpful assistant that answers questions about My Documentation.";
822
+
823
+ export const suggestions = [
824
+ "How do I get started?",
825
+ "How do I deploy?",
826
+ ];
827
+
828
+ export const agent = {
829
+ product: {
830
+ name: "My Product",
831
+ description: "My Product helps teams build and deploy applications.",
832
+ },
833
+ };
834
+
835
+ export const translations = {
836
+ en: { displayName: "English" },
837
+ };
838
+
839
+ export const basePath: string | undefined = undefined;
840
+ export const siteId: string | undefined = undefined;
841
+ ```
842
+
843
+ ## `defineConfig`
844
+
845
+ `lib/geistdocs/config.tsx` converts your root exports into a package config. Most projects only need the generated defaults:
846
+
847
+ ```tsx title="lib/geistdocs/config.tsx"
848
+ import { defineConfig } from "@vercel/geistdocs/config";
849
+ import {
850
+ agent,
851
+ basePath,
852
+ github,
853
+ Logo,
854
+ nav,
855
+ prompt,
856
+ siteId,
857
+ suggestions,
858
+ title,
859
+ translations,
860
+ } from "@/geistdocs";
861
+
862
+ export const config = defineConfig({
863
+ title,
864
+ agent,
865
+ defaultLanguage: "en",
866
+ logo: <Logo />,
867
+ github,
868
+ nav,
869
+ basePath,
870
+ siteId,
871
+ translations,
872
+ ai: {
873
+ prompt,
874
+ suggestions,
875
+ },
876
+ });
877
+ ```
878
+
879
+ Advanced sites can add `content` and `versions` metadata so local adapters and custom UI share one configuration object:
880
+
881
+ ```tsx title="lib/geistdocs/config.tsx"
882
+ export const config = defineConfig({
883
+ // ...
884
+ content: [
885
+ { id: "docs", label: "Docs", dir: "content/docs", route: "/docs" },
886
+ {
887
+ id: "cookbook",
888
+ label: "Cookbook",
889
+ dir: "content/cookbook",
890
+ route: "/cookbook",
891
+ },
892
+ ],
893
+ versions: {
894
+ current: "v6",
895
+ items: [
896
+ { id: "v6", label: "v6 latest" },
897
+ { id: "v5", label: "v5", href: "https://v5.example.com/:path*" },
898
+ ],
899
+ },
900
+ });
901
+ ```
902
+
903
+ Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
904
+
905
+ ## `source.config.ts`
906
+
907
+ Use the source-config-safe package export in `source.config.ts`. This file is evaluated by `fumadocs-mdx` during install and build, so it should avoid imports from runtime component entry points such as `@vercel/geistdocs/mdx`.
908
+
909
+ ```ts title="source.config.ts"
910
+ import {
911
+ defineGeistdocsSourceConfig,
912
+ geistdocsFrontmatterSchema,
913
+ geistdocsMetaSchema,
914
+ } from "@vercel/geistdocs/source-config";
915
+ import { defineDocs } from "fumadocs-mdx/config";
916
+
917
+ export const docs = defineDocs({
918
+ dir: "content/docs",
919
+ docs: {
920
+ schema: geistdocsFrontmatterSchema,
921
+ postprocess: {
922
+ includeProcessedMarkdown: true,
923
+ },
924
+ },
925
+ meta: {
926
+ schema: geistdocsMetaSchema,
927
+ },
928
+ });
929
+
930
+ export default defineGeistdocsSourceConfig();
931
+ ```
932
+
933
+ To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/"` in `createSource`. Root-mounted docs need explicit `markdownRoutes`; Geistdocs does not infer a broad `/*path` mapping because it can capture homepages and non-docs app routes.
934
+
935
+ ## Page actions
936
+
937
+ Page actions appear below the table of contents. They are enabled by default and can be disabled through `defineConfig` in `lib/geistdocs/config.tsx`:
938
+
939
+ ```tsx title="lib/geistdocs/config.tsx"
940
+ export const config = defineConfig({
941
+ // ...
942
+ pageActions: {
943
+ editSource: false,
944
+ scrollTop: true,
945
+ copyPage: true,
946
+ askAI: true,
947
+ openInChat: false,
948
+ },
949
+ feedback: {
950
+ enabled: false,
951
+ },
952
+ });
953
+ ```
954
+
955
+ `github.editPath` controls the file path used by the "Edit this page on GitHub" action. Use `{path}` where the page path should be inserted. For monorepos, include the app directory, such as `apps/docs/content/docs/{path}`.
956
+
957
+ ## Page visibility
958
+
959
+ Use frontmatter to control whether a page appears in package-owned machine-readable surfaces:
960
+
961
+ ```mdx title="content/docs/internal-note.mdx"
962
+ ---
963
+ title: Internal note
964
+ description: Hidden from public indexes
965
+ internal: true
966
+ ---
967
+ ```
968
+
969
+ `internal: true` excludes a page from `llms.txt`, `sitemap.md`, search, and chat. `noindex: true` adds `robots: noindex` metadata and excludes the page from `sitemap.md`. Use `excludeFrom` for per-surface control:
970
+
971
+ ```mdx
972
+ ---
973
+ title: Draft guide
974
+ excludeFrom:
975
+ - chat
976
+ - search
977
+ ---
978
+ ```
979
+
980
+ Optional `tags`, `keywords`, and `canonical` frontmatter are also recognized by the package runtime.
981
+
982
+ ## User-owned adapters
983
+
984
+ Adapter files are safe to edit. Package updates do not overwrite them.
985
+
986
+ For example, add a custom MDX component:
987
+
988
+ ```tsx title="components/geistdocs/mdx-components.tsx"
989
+ import { createMdxComponents } from "@vercel/geistdocs/mdx";
990
+ import type { MDXComponents } from "mdx/types";
991
+
992
+ const ProductCard = ({ name }: { name: string }) => <div>{name}</div>;
993
+
994
+ export const getMDXComponents = (components?: MDXComponents): MDXComponents =>
995
+ createMdxComponents({
996
+ ProductCard,
997
+ ...components,
998
+ });
999
+ ```
1000
+
1001
+ Then use it in MDX:
1002
+
1003
+ ```mdx
1004
+ <ProductCard name="My product" />
1005
+ ```
1006
+
1007
+ ## Docs page adapter
1008
+
1009
+ `createDocsPage` accepts hooks for route-specific behavior:
1010
+
1011
+ ```tsx title="app/[lang]/docs/[[...slug]]/page.tsx"
1012
+ const docsPage = createDocsPage({
1013
+ config,
1014
+ source: geistdocsSource,
1015
+ getPageUrl: ({ page }) => page.url,
1016
+ openGraph: {
1017
+ images: true,
1018
+ },
1019
+ metadata: ({ metadata }) => metadata,
1020
+ mdx: ({ link }) => getMDXComponents({ a: link }),
1021
+ });
1022
+ ```
1023
+
1024
+ Use `getPageUrl` when the public route differs from the source URL, such as `/v5/docs`. Set `openGraph.images` to `true` only when your site includes the Geistdocs OG route. Use `metadata` to set canonical URLs, `robots`, or custom Open Graph fields for a specific route.
1025
+
1026
+ ## Package-owned runtime
1027
+
1028
+ Do not edit files inside `node_modules/@vercel/geistdocs`. Update the package instead:
1029
+
1030
+ ```bash title="Terminal"
1031
+ pnpm exec geistdocs update
1032
+ ```
1033
+
1034
+ If a release adds an optional prop or config field, opt into it by editing the relevant local adapter file. Existing adapters should keep compiling unless a release includes a breaking API change.
1035
+
1036
+
1037
+ ---
1038
+
1039
+ ---
1040
+ title: Syntax
1041
+ description: Learn about the supported markdown syntax and formatting options
1042
+ type: reference
1043
+ summary: Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
1044
+ url: /docs/syntax
1045
+ source: apps/template/content/docs/syntax.mdx
1046
+ prerequisites:
1047
+ - /docs/getting-started
1048
+ related:
1049
+ - /docs/configuration
1050
+ ---
1051
+
1052
+ # Syntax
1053
+
1054
+ Geistdocs supports MDX, a superset of Markdown that allows you to use JSX components within your documentation. This guide covers all the formatting options available.
1055
+
1056
+ Help me write a Geistdocs MDX page. Use this page as a syntax reference and create an example page with frontmatter, headings, links, a code block, a `Callout`, and a `CopyPrompt` component.
1057
+
1058
+ ## Frontmatter
1059
+
1060
+ Every MDX file should include frontmatter at the top:
1061
+
1062
+ ```yaml
1063
+ ---
1064
+ title: Page Title
1065
+ description: A brief description of the page content
1066
+ ---
1067
+ ```
1068
+
1069
+ The `title` property is required and is used for the page heading and navigation. The `description` is used for SEO and page previews.
1070
+
1071
+ ## Basic Markdown
1072
+
1073
+ ### Text Formatting
1074
+
1075
+ You can style text using standard Markdown syntax:
1076
+
1077
+ - **Bold text** with `**double asterisks**`
1078
+ - _Italic text_ with `*single asterisks*`
1079
+ - ~~Strikethrough~~ with `~~double tildes~~`
1080
+ - `Inline code` with `` `backticks` ``
1081
+
1082
+ ### Headings
1083
+
1084
+ Use `#` symbols to create headings:
1085
+
1086
+ ```text
1087
+ # Heading 1
1088
+
1089
+ ## Heading 2
1090
+
1091
+ ### Heading 3
1092
+
1093
+ #### Heading 4
1094
+
1095
+ ##### Heading 5
1096
+
1097
+ ###### Heading 6
1098
+ ```
1099
+
1100
+ Headings automatically generate anchor links for navigation and deep linking.
1101
+
1102
+ ### Lists
1103
+
1104
+ Create unordered lists with `-`, `*`, or `+`:
1105
+
1106
+ - First item
1107
+ - Second item
1108
+ - Nested item
1109
+ - Another nested item
1110
+ - Third item
1111
+
1112
+ Create ordered lists with numbers:
1113
+
1114
+ 1. First step
1115
+ 2. Second step
1116
+ 3. Third step
1117
+
1118
+ ### Blockquotes
1119
+
1120
+ Use `>` to create blockquotes:
1121
+
1122
+ > This is a blockquote. You can use it to highlight important information or quotes from external sources.
1123
+
1124
+ ### Links
1125
+
1126
+ Create links with `[text](url)`:
1127
+
1128
+ - [External link](https://vercel.com)
1129
+ - [Internal link](/docs/getting-started)
1130
+
1131
+ ### Images
1132
+
1133
+ Add images with `![alt text](url)`:
1134
+
1135
+ ```md
1136
+ ![Description of the image](/path/to/image.png)
1137
+ ```
1138
+
1139
+ ## GitHub Flavored Markdown
1140
+
1141
+ Geistdocs supports GFM extensions including tables, task lists, and autolinks.
1142
+
1143
+ ### Tables
1144
+
1145
+ Create tables using pipes and dashes:
1146
+
1147
+ ```md
1148
+ | Feature | Description | Status |
1149
+ | -------- | ----------------- | --------- |
1150
+ | Markdown | Basic formatting | Supported |
1151
+ | GFM | GitHub extensions | Supported |
1152
+ | MDX | JSX in Markdown | Supported |
1153
+ ```
1154
+
1155
+ This renders as:
1156
+
1157
+ | Feature | Description | Status |
1158
+ | -------- | ----------------- | --------- |
1159
+ | Markdown | Basic formatting | Supported |
1160
+ | GFM | GitHub extensions | Supported |
1161
+ | MDX | JSX in Markdown | Supported |
1162
+
1163
+ ### Task Lists
1164
+
1165
+ Create interactive task lists:
1166
+
1167
+ ```md
1168
+ - [x] Completed task
1169
+ - [ ] Incomplete task
1170
+ - [ ] Another task to do
1171
+ ```
1172
+
1173
+ This renders as:
1174
+
1175
+ - [x] Completed task
1176
+ - [ ] Incomplete task
1177
+ - [ ] Another task to do
1178
+
1179
+ ### Autolinks
1180
+
1181
+ URLs are automatically converted to clickable links:
1182
+
1183
+ ```md
1184
+ https://vercel.com
1185
+ ```
1186
+
1187
+ This renders as:
1188
+
1189
+ https://vercel.com
1190
+
1191
+ ## Code Blocks
1192
+
1193
+ Fenced code blocks support syntax highlighting for many languages.
1194
+
1195
+ ### Basic Syntax Highlighting
1196
+
1197
+ Specify the language after the opening backticks:
1198
+
1199
+ ````md
1200
+ ```typescript
1201
+ const greet = (name: string): string => {
1202
+ return `Hello, ${name}!`;
1203
+ };
1204
+ ```
1205
+ ````
1206
+
1207
+ This renders as:
1208
+
1209
+ ```typescript
1210
+ const greet = (name: string): string => {
1211
+ return `Hello, ${name}!`;
1212
+ };
1213
+ ```
1214
+
1215
+ ### Titles
1216
+
1217
+ Add a title to your code block with the `title` attribute:
1218
+
1219
+ ````md
1220
+ ```tsx title="components/button.tsx"
1221
+ export const Button = ({ children }) => {
1222
+ return <button type="button">{children}</button>;
1223
+ };
1224
+ ```
1225
+ ````
1226
+
1227
+ This renders as:
1228
+
1229
+ ```tsx title="components/button.tsx"
1230
+ export const Button = ({ children }) => {
1231
+ return <button type="button">{children}</button>;
1232
+ };
1233
+ ```
1234
+
1235
+ ### Line Numbers
1236
+
1237
+ Display line numbers by adding the `lineNumbers` attribute:
1238
+
1239
+ ````md
1240
+ ```typescript lineNumbers
1241
+ const numbers = [1, 2, 3, 4, 5];
1242
+ const doubled = numbers.map((n) => n * 2);
1243
+ console.log(doubled);
1244
+ ```
1245
+ ````
1246
+
1247
+ This renders as:
1248
+
1249
+ ```typescript lineNumbers
1250
+ const numbers = [1, 2, 3, 4, 5];
1251
+ const doubled = numbers.map((n) => n * 2);
1252
+ console.log(doubled);
1253
+ ```
1254
+
1255
+ ### Line Highlighting
1256
+
1257
+ Highlight specific lines using the `[!code highlight]` comment:
1258
+
1259
+ ````md
1260
+ ```typescript
1261
+ const config = {
1262
+ theme: "dark", // [ !code highlight]
1263
+ language: "en",
1264
+ };
1265
+ ```
1266
+ ````
1267
+
1268
+ Remove the space before `!` when using this syntax. This renders as:
1269
+
1270
+ ```typescript
1271
+ const config = {
1272
+ theme: "dark", // [!code highlight]
1273
+ language: "en",
1274
+ };
1275
+ ```
1276
+
1277
+ ### Word Highlighting
1278
+
1279
+ Highlight specific words with `[!code word:term]`:
1280
+
1281
+ ````md
1282
+ ```typescript
1283
+ // [ !code word:config]
1284
+ const config = {
1285
+ theme: "dark",
1286
+ };
1287
+
1288
+ console.log(config);
1289
+ ```
1290
+ ````
1291
+
1292
+ Remove the space before `!` when using this syntax. This renders as:
1293
+
1294
+ ```typescript
1295
+ // [!code word:config]
1296
+ const config = {
1297
+ theme: "dark",
1298
+ };
1299
+
1300
+ console.log(config);
1301
+ ```
1302
+
1303
+ ### Diff Syntax
1304
+
1305
+ Show additions and deletions with `[!code ++]` and `[!code --]`:
1306
+
1307
+ ````md
1308
+ ```typescript
1309
+ const config = {
1310
+ theme: "light", // [ !code --]
1311
+ theme: "dark", // [ !code ++]
1312
+ language: "en",
1313
+ };
1314
+ ```
1315
+ ````
1316
+
1317
+ Remove the space before `!` when using this syntax. This renders as:
1318
+
1319
+ ```typescript
1320
+ const config = {
1321
+ theme: "light", // [!code --]
1322
+ theme: "dark", // [!code ++]
1323
+ language: "en",
1324
+ };
1325
+ ```
1326
+
1327
+ ### Focus Lines
1328
+
1329
+ Draw attention to specific lines with `[!code focus]`:
1330
+
1331
+ ````md
1332
+ ```typescript
1333
+ const numbers = [1, 2, 3, 4, 5];
1334
+ const sum = numbers.reduce((a, b) => a + b, 0); // [ !code focus]
1335
+ console.log(sum);
1336
+ ```
1337
+ ````
1338
+
1339
+ Remove the space before `!` when using this syntax. This renders as:
1340
+
1341
+ ```typescript
1342
+ const numbers = [1, 2, 3, 4, 5];
1343
+ const sum = numbers.reduce((a, b) => a + b, 0); // [!code focus]
1344
+ console.log(sum);
1345
+ ```
1346
+
1347
+ ## Mermaid Diagrams
1348
+
1349
+ Create diagrams and flowcharts using Mermaid syntax.
1350
+
1351
+ ### Flowcharts
1352
+
1353
+ ````md
1354
+ ```mermaid
1355
+ graph TD;
1356
+ A[Start] --> B{Is it working?};
1357
+ B -->|Yes| C[Great!];
1358
+ B -->|No| D[Debug];
1359
+ D --> B;
1360
+ ```
1361
+ ````
1362
+
1363
+ This renders as:
1364
+
1365
+ ```mermaid
1366
+ graph TD;
1367
+ A[Start] --> B{Is it working?};
1368
+ B -->|Yes| C[Great!];
1369
+ B -->|No| D[Debug];
1370
+ D --> B;
1371
+ ```
1372
+
1373
+ ### Sequence Diagrams
1374
+
1375
+ ````md
1376
+ ```mermaid
1377
+ sequenceDiagram
1378
+ participant User
1379
+ participant API
1380
+ participant Database
1381
+ User->>API: Request data
1382
+ API->>Database: Query
1383
+ Database-->>API: Results
1384
+ API-->>User: Response
1385
+ ```
1386
+ ````
1387
+
1388
+ This renders as:
1389
+
1390
+ ```mermaid
1391
+ sequenceDiagram
1392
+ participant User
1393
+ participant API
1394
+ participant Database
1395
+ User->>API: Request data
1396
+ API->>Database: Query
1397
+ Database-->>API: Results
1398
+ API-->>User: Response
1399
+ ```
1400
+
1401
+ ### Architecture Diagrams
1402
+
1403
+ ````md
1404
+ ```mermaid
1405
+ graph TD;
1406
+ subgraph Frontend
1407
+ A[Web App]
1408
+ B[Mobile App]
1409
+ end
1410
+ subgraph Backend
1411
+ C[API Gateway]
1412
+ D[Auth Service]
1413
+ E[Data Service]
1414
+ end
1415
+ subgraph Storage
1416
+ F[(Database)]
1417
+ G[(Cache)]
1418
+ end
1419
+ A --> C
1420
+ B --> C
1421
+ C --> D
1422
+ C --> E
1423
+ E --> F
1424
+ E --> G
1425
+ ```
1426
+ ````
1427
+
1428
+ This renders as:
1429
+
1430
+ ```mermaid
1431
+ graph TD;
1432
+ subgraph Frontend
1433
+ A[Web App]
1434
+ B[Mobile App]
1435
+ end
1436
+ subgraph Backend
1437
+ C[API Gateway]
1438
+ D[Auth Service]
1439
+ E[Data Service]
1440
+ end
1441
+ subgraph Storage
1442
+ F[(Database)]
1443
+ G[(Cache)]
1444
+ end
1445
+ A --> C
1446
+ B --> C
1447
+ C --> D
1448
+ C --> E
1449
+ E --> F
1450
+ E --> G
1451
+ ```
1452
+
1453
+
1454
+ ---
1455
+
1456
+ ---
1457
+ title: Geistdocs Provider
1458
+ description: The root provider component that handles notifications, search and analytics
1459
+ type: reference
1460
+ summary: The root provider component that wraps your application to handle toast notifications, search, and analytics.
1461
+ url: /docs/provider
1462
+ source: apps/template/content/docs/provider.mdx
1463
+ prerequisites:
1464
+ - /docs/getting-started
1465
+ related:
1466
+ - /docs/configuration
1467
+ ---
1468
+
1469
+ # Geistdocs Provider
1470
+
1471
+ The `GeistdocsProvider` wraps the root of your application with package-managed UI state. It connects theme, search, AI chat, notifications, and optional analytics to the rest of your Geistdocs site.
1472
+
1473
+ Review my Geistdocs provider setup. Check that the root layout wraps the app with `GeistdocsProvider`, that config is passed correctly, and that analytics, search, theme, and Ask AI behavior are wired safely.
1474
+
1475
+ ## What it does
1476
+
1477
+ The provider handles these behaviors:
1478
+
1479
+ 1. **Toast notifications**: Provides a global notification system for user feedback.
1480
+ 2. **Analytics**: Integrates Vercel Analytics and Speed Insights when the local adapter includes them.
1481
+ 3. **Search**: Configures the search dialog and connects it to your search API.
1482
+ 4. **Ask AI**: Provides the client state used by the chat sidebar and page actions.
1483
+
1484
+ ## Usage
1485
+
1486
+ Ensure your application is wrapped with the provider in your root layout:
1487
+
1488
+ ```tsx title="app/layout.tsx"
1489
+ import { GeistdocsProvider } from "@/components/geistdocs/provider";
1490
+
1491
+ const Layout = ({ children }: LayoutProps) => (
1492
+ <html lang="en">
1493
+ <body>
1494
+ <GeistdocsProvider>
1495
+ <Navbar />
1496
+ {children}
1497
+ </GeistdocsProvider>
1498
+ </body>
1499
+ </html>
1500
+ );
1501
+ ```
1502
+
1503
+ The generated local adapter imports the package provider and passes your site config to it.
1504
+
1505
+ ## AI Sidebar
1506
+
1507
+ When users open the AI chat on desktop, the provider automatically adds padding to prevent content from being hidden behind the sidebar. On mobile, the chat opens as a drawer instead, so no padding is needed.
1508
+
1509
+ The provider detects the screen size and chat state.
1510
+
1511
+ ## Toast Notifications
1512
+
1513
+ The provider includes a global toast notification system. Use it anywhere in your app:
1514
+
1515
+ ```tsx title="page.tsx"
1516
+ import { toast } from "sonner";
1517
+
1518
+ toast.success("Changes saved");
1519
+ toast.error("Something went wrong");
1520
+ ```
1521
+
1522
+ ## Analytics
1523
+
1524
+ Vercel Analytics is automatically included and tracks:
1525
+
1526
+ - Page views
1527
+ - Web Vitals
1528
+ - User interactions
1529
+ - Performance metrics
1530
+
1531
+ No configuration needed - it works automatically when deployed on Vercel.
1532
+
1533
+
1534
+ ---
1535
+
1536
+ ---
1537
+ title: Versioned docs
1538
+ description: Configure multiple documentation versions with package-backed source helpers
1539
+ type: guide
1540
+ summary: Use createVersionedSources to configure stable, pre-release, or host-based documentation versions.
1541
+ url: /docs/versioned-docs
1542
+ source: apps/template/content/docs/versioned-docs.mdx
1543
+ prerequisites:
1544
+ - /docs/configuration
1545
+ related:
1546
+ - /docs/proxy
1547
+ - /docs/llms-txt
1548
+ ---
1549
+
1550
+ # Versioned docs
1551
+
1552
+ Versioned docs let you serve multiple documentation sets from one Geistdocs project. Use them for stable and pre-release docs, previous major versions, or host-based version switching.
1553
+
1554
+ Help me add versioned docs to this Geistdocs site. Inspect `source.config.ts`, `lib/geistdocs/source.ts`, app route files, and the docs layout, then propose a versioned source setup using `createVersionedSources`.
1555
+
1556
+ ## Configure source collections
1557
+
1558
+ Create one Fumadocs collection for each version in `source.config.ts`:
1559
+
1560
+ ```ts title="source.config.ts"
1561
+ import {
1562
+ defineGeistdocsSourceConfig,
1563
+ geistdocsFrontmatterSchema,
1564
+ } from "@vercel/geistdocs/source-config";
1565
+ import { defineDocs } from "fumadocs-mdx/config";
1566
+
1567
+ export const v4docs = defineDocs({
1568
+ dir: "content/docs/v4",
1569
+ docs: {
1570
+ schema: geistdocsFrontmatterSchema,
1571
+ postprocess: {
1572
+ includeProcessedMarkdown: true,
1573
+ },
1574
+ },
1575
+ });
1576
+
1577
+ export const v5docs = defineDocs({
1578
+ dir: "content/docs/v5",
1579
+ docs: {
1580
+ schema: geistdocsFrontmatterSchema,
1581
+ postprocess: {
1582
+ includeProcessedMarkdown: true,
1583
+ },
1584
+ },
1585
+ });
1586
+
1587
+ export default defineGeistdocsSourceConfig();
1588
+ ```
1589
+
1590
+ ## Create versioned sources
1591
+
1592
+ Use `createVersionedSources` in `lib/geistdocs/source.ts`:
1593
+
1594
+ ```ts title="lib/geistdocs/source.ts"
1595
+ import { createVersionedSources } from "@vercel/geistdocs/source";
1596
+ import { v4docs, v5docs } from "@/.source/server";
1597
+ import { config } from "./config";
1598
+
1599
+ export const versions = createVersionedSources({
1600
+ config,
1601
+ current: "v4",
1602
+ versions: [
1603
+ {
1604
+ id: "v4",
1605
+ label: "v4",
1606
+ docs: v4docs,
1607
+ baseUrl: "/docs",
1608
+ },
1609
+ {
1610
+ id: "v5",
1611
+ label: "v5 pre-release",
1612
+ docs: v5docs,
1613
+ baseUrl: "/docs",
1614
+ routePrefix: "/v5",
1615
+ },
1616
+ ],
1617
+ });
1618
+
1619
+ export const geistdocsSource = versions.current;
1620
+ export const source = geistdocsSource.source;
1621
+ ```
1622
+
1623
+ The returned object includes:
1624
+
1625
+ | Property | Type | Description |
1626
+ | --- | --- | --- |
1627
+ | `current` | `GeistdocsSourceBundle` | The source matching the `current` version ID. |
1628
+ | `byId` | `Record<string, GeistdocsSourceBundle>` | A map of version IDs to source bundles. |
1629
+ | `all` | `Array` | Version metadata and source bundles for rendering UI. |
1630
+ | `currentVersion` | `string` | The active version ID. |
1631
+
1632
+ ## Render versioned pages
1633
+
1634
+ Use the current version for `/docs` and a specific version for version-prefixed routes:
1635
+
1636
+ ```tsx title="app/[lang]/docs/[[...slug]]/page.tsx"
1637
+ import { createDocsPage } from "@vercel/geistdocs/pages/docs";
1638
+ import { config } from "@/lib/geistdocs/config";
1639
+ import { versions } from "@/lib/geistdocs/source";
1640
+
1641
+ const docsPage = createDocsPage({
1642
+ config,
1643
+ source: versions.current,
1644
+ });
1645
+
1646
+ export default docsPage.Page;
1647
+ export const generateStaticParams = docsPage.generateStaticParams;
1648
+ export const generateMetadata = docsPage.generateMetadata;
1649
+ ```
1650
+
1651
+ ```tsx title="app/[lang]/v5/docs/[[...slug]]/page.tsx"
1652
+ import { createDocsPage } from "@vercel/geistdocs/pages/docs";
1653
+ import { config } from "@/lib/geistdocs/config";
1654
+ import { versions } from "@/lib/geistdocs/source";
1655
+
1656
+ const docsPage = createDocsPage({
1657
+ config,
1658
+ source: versions.byId.v5,
1659
+ getPageUrl: ({ page }) => `/v5${page.url}`,
1660
+ metadata: ({ metadata }) => ({
1661
+ ...metadata,
1662
+ robots: {
1663
+ index: false,
1664
+ follow: true,
1665
+ },
1666
+ }),
1667
+ });
1668
+
1669
+ export default docsPage.Page;
1670
+ export const generateStaticParams = docsPage.generateStaticParams;
1671
+ export const generateMetadata = docsPage.generateMetadata;
1672
+ ```
1673
+
1674
+ Use `getPageUrl` when the route path differs from the source `baseUrl`. This keeps page actions and markdown links pointed at the public URL.
1675
+
1676
+ ## Add a version selector
1677
+
1678
+ Use `GeistdocsVersionSelect` when readers need to move between versions:
1679
+
1680
+ ```tsx title="components/geistdocs/docs-layout.tsx"
1681
+ import { GeistdocsDocsLayout } from "@vercel/geistdocs/layout";
1682
+ import { GeistdocsVersionSelect } from "@vercel/geistdocs/versions";
1683
+ import { config } from "@/lib/geistdocs/config";
1684
+
1685
+ export const DocsLayout = ({ tree, children }: DocsLayoutProps) => (
1686
+ <GeistdocsDocsLayout
1687
+ config={config}
1688
+ sidebarTop={
1689
+ <GeistdocsVersionSelect
1690
+ current="v4"
1691
+ versions={[
1692
+ { id: "v4", label: "v4" },
1693
+ { id: "v5", label: "v5 pre-release", routePrefix: "/v5" },
1694
+ ]}
1695
+ />
1696
+ }
1697
+ tree={tree}
1698
+ >
1699
+ {children}
1700
+ </GeistdocsDocsLayout>
1701
+ );
1702
+ ```
1703
+
1704
+ Each version can define an `icon` to override the default current/previous version icons:
1705
+
1706
+ ```tsx
1707
+ <GeistdocsVersionSelect
1708
+ current="v6"
1709
+ versions={[
1710
+ { id: "v6", label: "v6 latest", icon: <span>6</span> },
1711
+ { id: "v5", label: "v5", icon: <span>5</span>, routePrefix: "/v5" },
1712
+ ]}
1713
+ />
1714
+ ```
1715
+
1716
+ Use `GeistdocsRouteSelect` for framework, product, or route switchers that should not use version-specific labels:
1717
+
1718
+ ```tsx
1719
+ import { LogoNextjs, LogoSvelteKit } from "@vercel/geistdocs/assets/logos";
1720
+ import { GeistdocsRouteSelect } from "@vercel/geistdocs/versions";
1721
+
1722
+ <GeistdocsRouteSelect
1723
+ ariaLabel="Select framework"
1724
+ current="nextjs"
1725
+ items={[
1726
+ {
1727
+ id: "nextjs",
1728
+ label: "Next.js",
1729
+ description: "React framework",
1730
+ icon: <LogoNextjs height={18} />,
1731
+ href: "/:path*",
1732
+ },
1733
+ {
1734
+ id: "sveltekit",
1735
+ label: "SvelteKit",
1736
+ description: "Svelte framework",
1737
+ icon: <LogoSvelteKit height={18} />,
1738
+ routePrefix: "/sveltekit",
1739
+ href: "/sveltekit/:path*",
1740
+ },
1741
+ ]}
1742
+ />
1743
+ ```
1744
+
1745
+ For host-based versions, use `href` instead of `routePrefix`:
1746
+
1747
+ ```tsx
1748
+ <GeistdocsVersionSelect
1749
+ current="v6"
1750
+ versions={[
1751
+ { id: "v6", label: "v6 latest" },
1752
+ { id: "v5", label: "v5", href: "https://v5.example.com/:path*" },
1753
+ { id: "v4", label: "v4", href: "https://v4.example.com/:path*" },
1754
+ ]}
1755
+ />
1756
+ ```
1757
+
1758
+ ## Configure markdown routes
1759
+
1760
+ Each public route family needs a matching markdown route in `proxy.ts`. Read [Proxy and markdown routes](/docs/proxy) for the proxy configuration.
1761
+
1762
+ ## Next steps
1763
+
1764
+ - Read [Proxy and markdown routes](/docs/proxy) to connect versioned pages to `.md`, `.mdx`, and AI-agent rewrites.
1765
+ - Read [llms.txt](/docs/llms-txt) to configure all-docs markdown output for multiple sources.
1766
+
1767
+
1768
+ ---
1769
+
1770
+ ---
1771
+ title: Proxy and markdown routes
1772
+ description: Add custom request logic while keeping Geistdocs markdown negotiation in the package
1773
+ type: reference
1774
+ summary: Configure createProxy with before and after hooks, markdown route mappings, and a static Next.js matcher.
1775
+ url: /docs/proxy
1776
+ source: apps/template/content/docs/proxy.mdx
1777
+ prerequisites:
1778
+ - /docs/configuration
1779
+ related:
1780
+ - /docs/migration
1781
+ - /docs/md
1782
+ - /docs/llms-txt
1783
+ - /docs/versioned-docs
1784
+ ---
1785
+
1786
+ # Proxy and markdown routes
1787
+
1788
+ The Geistdocs proxy handles markdown negotiation, AI-agent rewrites, request tracking, and i18n fallback. Add site-specific request logic with hooks instead of copying the package proxy implementation.
1789
+
1790
+ Review this Geistdocs `proxy.ts` file. Check that `export const config` is static, custom logic is inside `createProxy` `before` or `after` hooks, and `markdownRoutes` cover every public docs route family.
1791
+
1792
+ ## Basic proxy
1793
+
1794
+ Generated projects use `createProxy` with the default `/docs` markdown route:
1795
+
1796
+ ```ts title="proxy.ts"
1797
+ import { createProxy } from "@vercel/geistdocs/proxy";
1798
+ import { config as geistdocsConfig } from "@/lib/geistdocs/config";
1799
+ import { trackMdRequest } from "@/lib/geistdocs/md-tracking";
1800
+
1801
+ const proxy = createProxy({
1802
+ config: geistdocsConfig,
1803
+ trackMarkdownRequest: trackMdRequest,
1804
+ });
1805
+
1806
+ export const config = {
1807
+ matcher: [
1808
+ "/((?!api(?:/|$)|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
1809
+ ],
1810
+ };
1811
+
1812
+ export default proxy;
1813
+ ```
1814
+
1815
+ Keep `export const config` as a static object. Next.js reads proxy matchers at build time and does not support calling a helper for this export.
1816
+
1817
+ ## Custom request logic
1818
+
1819
+ Use `before` for logic that should run before Geistdocs markdown handling. Return a `Response` to stop processing.
1820
+
1821
+ ```ts title="proxy.ts"
1822
+ import { createProxy } from "@vercel/geistdocs/proxy";
1823
+ import { NextResponse } from "next/server";
1824
+ import { config as geistdocsConfig } from "@/lib/geistdocs/config";
1825
+
1826
+ const proxy = createProxy({
1827
+ config: geistdocsConfig,
1828
+ before: async ({ request, defaultLanguage }) => {
1829
+ if (request.nextUrl.pathname === "/") {
1830
+ return NextResponse.rewrite(
1831
+ new URL(`/${defaultLanguage}/home`, request.url)
1832
+ );
1833
+ }
1834
+
1835
+ return null;
1836
+ },
1837
+ });
1838
+ ```
1839
+
1840
+ Use `after` for logic that should run after markdown handling but before the i18n fallback:
1841
+
1842
+ ```ts title="proxy.ts"
1843
+ const proxy = createProxy({
1844
+ config: geistdocsConfig,
1845
+ after: async ({ request }) => {
1846
+ const session = await getSessionFromReq(request);
1847
+
1848
+ if (!session) {
1849
+ return null;
1850
+ }
1851
+
1852
+ return refreshSession(request, session);
1853
+ },
1854
+ });
1855
+ ```
1856
+
1857
+ ## Markdown route mappings
1858
+
1859
+ 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.
1860
+
1861
+ 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.
1862
+
1863
+ ```tsx title="lib/geistdocs/config.tsx"
1864
+ export const config = defineConfig({
1865
+ // ...
1866
+ content: [{ id: "docs", label: "Docs", dir: "content/docs", route: "/docs" }],
1867
+ });
1868
+ ```
1869
+
1870
+ Use `markdownRoutes` when you need to override the inferred mappings:
1871
+
1872
+ ```ts title="proxy.ts"
1873
+ const proxy = createProxy({
1874
+ config: geistdocsConfig,
1875
+ markdownRoutes: [
1876
+ { from: "/docs/*path", to: "/[lang]/llms.mdx/*path" },
1877
+ { from: "/cookbook/*path", to: "/[lang]/llms.mdx/cookbook/*path" },
1878
+ { from: "/v5/docs/*path", to: "/[lang]/v5/llms.mdx/*path" },
1879
+ ],
1880
+ });
1881
+ ```
1882
+
1883
+ With these mappings:
1884
+
1885
+ | Request | Rewritten destination |
1886
+ | --- | --- |
1887
+ | `/docs/getting-started.md` | `/en/llms.mdx/getting-started` |
1888
+ | `/cookbook/install.mdx` | `/en/llms.mdx/cookbook/install` |
1889
+ | `/v5/docs/intro` with `Accept: text/markdown` | `/en/v5/llms.mdx/intro` |
1890
+
1891
+ Use `[lang]` in the destination when your markdown route is nested under `app/[lang]`. Use `*path` or `:path*` to insert the matched wildcard path.
1892
+
1893
+ ## Root-mounted docs
1894
+
1895
+ For docs served from the site root, set the source `baseUrl` and config route to `/`:
1896
+
1897
+ ```ts title="lib/geistdocs/source.ts"
1898
+ export const geistdocsSource = createSource({
1899
+ docs,
1900
+ config,
1901
+ baseUrl: "/",
1902
+ });
1903
+ ```
1904
+
1905
+ ```tsx title="lib/geistdocs/config.tsx"
1906
+ export const config = defineConfig({
1907
+ // ...
1908
+ content: [{ id: "docs", label: "Docs", dir: "content/docs", route: "/" }],
1909
+ });
1910
+ ```
1911
+
1912
+ If the whole site is documentation and there is no separate homepage, you can map all root paths to page-level Markdown:
1913
+
1914
+ ```ts title="proxy.ts"
1915
+ const proxy = createProxy({
1916
+ config: geistdocsConfig,
1917
+ markdownRoutes: [{ from: "/*path", to: "/[lang]/llms.mdx/*path" }],
1918
+ });
1919
+ ```
1920
+
1921
+ If a homepage or app routes also live at `/`, do not use a broad `/*path` mapping. Enumerate each docs route family instead:
1922
+
1923
+ ```ts title="proxy.ts"
1924
+ const proxy = createProxy({
1925
+ config: geistdocsConfig,
1926
+ markdownRoutes: [
1927
+ { from: "/api-reference/*path", to: "/[lang]/llms.mdx/api-reference/*path" },
1928
+ { from: "/guides/*path", to: "/[lang]/llms.mdx/guides/*path" },
1929
+ { from: "/concepts/*path", to: "/[lang]/llms.mdx/concepts/*path" },
1930
+ ],
1931
+ });
1932
+ ```
1933
+
1934
+ ## Hook context
1935
+
1936
+ Both `before` and `after` receive the same context:
1937
+
1938
+ | Property | Type | Description |
1939
+ | --- | --- | --- |
1940
+ | `request` | `NextRequest` | The incoming request. |
1941
+ | `context` | `NextFetchEvent` | The proxy event, including `waitUntil`. |
1942
+ | `defaultLanguage` | `string` | The configured default language. |
1943
+ | `languages` | `string[]` | All configured languages. |
1944
+
1945
+ ## Next steps
1946
+
1947
+ - Read [.md extension](/docs/md) to understand single-page Markdown responses.
1948
+ - Read [Migration guide](/docs/migration) to move existing middleware behavior into `createProxy` hooks.
1949
+ - Read [Versioned docs](/docs/versioned-docs) to map multiple public route families.
1950
+
1951
+
1952
+ ---
1953
+
1954
+ ---
1955
+ title: .md Extension
1956
+ description: Access documentation pages as raw Markdown by appending .md or .mdx to any URL
1957
+ type: conceptual
1958
+ summary: Access any documentation page as raw Markdown by appending .md or .mdx to the URL for AI tool consumption.
1959
+ url: /docs/md
1960
+ source: apps/template/content/docs/md.mdx
1961
+ related:
1962
+ - /docs/agent-readiness
1963
+ - /docs/llms-txt
1964
+ - /docs/proxy
1965
+ ---
1966
+
1967
+ # .md Extension
1968
+
1969
+ Geistdocs lets AI tools and language models access documentation pages as plain Markdown. Append `.md` or `.mdx` to a documentation URL to get the processed Markdown content for that page.
1970
+
1971
+ Help me test raw Markdown routes in this Geistdocs project. Fetch a docs page with `.mdx` appended, compare it to the rendered page, and explain how AI tools can use it.
1972
+
1973
+ ## How it works
1974
+
1975
+ When you add `.md` or `.mdx` to a documentation URL, Geistdocs returns the page content as Markdown instead of rendered HTML. AI tools can use that response as focused context for one page.
1976
+
1977
+ ### Example
1978
+
1979
+ ```
1980
+ # Normal page
1981
+ https://yourdomain.com/docs/getting-started
1982
+
1983
+ # Markdown version
1984
+ https://yourdomain.com/docs/getting-started.mdx
1985
+ ```
1986
+
1987
+ The `.mdx` version returns:
1988
+
1989
+ - The page title as an H1 heading
1990
+ - The full processed Markdown content
1991
+ - No HTML, styling, or navigation
1992
+
1993
+ ## Use cases
1994
+
1995
+ This feature is particularly useful for:
1996
+
1997
+ - **AI Chat Tools** - Tools like ChatGPT, Claude, and Cursor can fetch and read your docs
1998
+ - **LLM Context** - Provides clean text for language model prompts
1999
+ - **Documentation Analysis** - Extract content for processing or analysis
2000
+ - **Content Migration** - Export documentation in a clean format
2001
+
2002
+ ## Implementation
2003
+
2004
+ The package proxy routes `.md` and `.mdx` requests to the package-backed markdown route handler:
2005
+
2006
+ ```ts title="proxy.ts"
2007
+ const proxy = createProxy({
2008
+ config: geistdocsConfig,
2009
+ markdownRoutes: [
2010
+ { from: "/docs/*path", to: "/[lang]/llms.mdx/*path" },
2011
+ ],
2012
+ });
2013
+ ```
2014
+
2015
+ The destination route uses `createDocsMarkdownRoute` to process the page and return Markdown with a `text/markdown` content type:
2016
+
2017
+ ```ts title="app/[lang]/llms.mdx/[[...slug]]/route.ts"
2018
+ import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
2019
+ import { geistdocsSource } from "@/lib/geistdocs/source";
2020
+
2021
+ export const { GET, generateStaticParams, revalidate } =
2022
+ createDocsMarkdownRoute({
2023
+ sources: [geistdocsSource],
2024
+ });
2025
+ ```
2026
+
2027
+ Read [Proxy and markdown routes](/docs/proxy) to configure additional route families such as `/cookbook` or `/v5/docs`.
2028
+
2029
+ ## Response Format
2030
+
2031
+ The response includes:
2032
+
2033
+ - Content-Type: `text/markdown`
2034
+ - The page title as a level 1 heading
2035
+ - Processed Markdown content from Fumadocs
2036
+
2037
+ All MDX components are processed and converted to plain Markdown equivalents.
2038
+
2039
+
2040
+ ---
2041
+
2042
+ ---
2043
+ title: Agent readiness
2044
+ description: Expose agents.md and MCP discovery files that help AI agents discover and use your docs site
2045
+ type: guide
2046
+ summary: Generate /agents.md and /.well-known/mcp.json from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
2047
+ url: /docs/agent-readiness
2048
+ source: apps/template/content/docs/agent-readiness.mdx
2049
+ related:
2050
+ - /docs/llms-txt
2051
+ - /docs/md
2052
+ - /docs/proxy
2053
+ ---
2054
+
2055
+ # Agent readiness
2056
+
2057
+ Geistdocs can generate `/agents.md` and `/.well-known/mcp.json` discovery files from your site config. These files tell AI agents where your docs live and which machine-readable integration surfaces your product declares.
2058
+
2059
+ Review this Geistdocs site's `/agents.md` and `/.well-known/mcp.json` files. Check whether they list the product description, documentation links, `llms.txt`, `sitemap.md`, OpenAPI specs, and MCP servers accurately.
2060
+
2061
+ ## What it provides
2062
+
2063
+ 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.
2064
+
2065
+ It can include:
2066
+
2067
+ - Product name, description, category, audience, and use cases
2068
+ - Human-readable docs entry points
2069
+ - `/llms.txt` for full documentation context
2070
+ - `/sitemap.md` for semantic navigation
2071
+ - Page-level Markdown guidance for `.md` and `.mdx` URLs
2072
+ - OpenAPI, authentication, scopes, rate limit, and error docs when configured
2073
+ - MCP manifests and server URLs when configured
2074
+ - Additional links and agent instructions
2075
+
2076
+ ## Add the route
2077
+
2078
+ Generated projects include a thin App Router adapter:
2079
+
2080
+ ```ts title="app/[lang]/agents.md/route.ts"
2081
+ import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
2082
+ import { config } from "@/lib/geistdocs/config";
2083
+
2084
+ export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
2085
+ config,
2086
+ });
2087
+ ```
2088
+
2089
+ Because the route is under `[lang]`, the Geistdocs proxy can serve `/agents.md` through the default language route.
2090
+
2091
+ Generated projects also include a thin adapter for MCP discovery:
2092
+
2093
+ ```ts title="app/[lang]/.well-known/mcp.json/route.ts"
2094
+ import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
2095
+ import { config } from "@/lib/geistdocs/config";
2096
+
2097
+ export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
2098
+ config,
2099
+ });
2100
+ ```
2101
+
2102
+ The MCP discovery route returns `404` until you configure `agent.mcp.servers`, so generated sites do not claim MCP support by default.
2103
+
2104
+ When configured, `/.well-known/mcp.json` returns the declared MCP servers:
2105
+
2106
+ ```json
2107
+ {
2108
+ "name": "My Product",
2109
+ "description": "My Product helps teams build and deploy applications.",
2110
+ "servers": [
2111
+ {
2112
+ "name": "My Product MCP",
2113
+ "url": "https://example.com/api/mcp",
2114
+ "description": "Use product tools through MCP."
2115
+ }
2116
+ ]
2117
+ }
2118
+ ```
2119
+
2120
+ ## Configure agent metadata
2121
+
2122
+ Add agent-readiness metadata in `geistdocs.tsx`, then pass it through `defineConfig` in `lib/geistdocs/config.tsx`.
2123
+
2124
+ ```tsx title="geistdocs.tsx"
2125
+ import type { GeistdocsAgentReadinessConfig } from "@vercel/geistdocs/config";
2126
+
2127
+ export const agent = {
2128
+ product: {
2129
+ name: "My Product",
2130
+ description: "My Product helps teams build and deploy applications.",
2131
+ category: "Developer tools",
2132
+ audience: ["Frontend developers", "Platform teams"],
2133
+ useCases: ["Deploy applications", "Manage domains", "Inspect logs"],
2134
+ },
2135
+ api: {
2136
+ openApiUrl: "https://api.example.com/openapi.json",
2137
+ openApiSpecs: [
2138
+ {
2139
+ label: "Admin API OpenAPI specification",
2140
+ url: "https://api.example.com/admin/openapi.json",
2141
+ description: "Administrative API operations.",
2142
+ },
2143
+ ],
2144
+ authDocsUrl: "/docs/authentication",
2145
+ scopesDocsUrl: "/docs/scopes",
2146
+ rateLimitsUrl: "/docs/rate-limits",
2147
+ errorsUrl: "/docs/errors",
2148
+ },
2149
+ mcp: {
2150
+ manifestUrl: "/.well-known/mcp.json",
2151
+ servers: [
2152
+ {
2153
+ name: "My Product MCP",
2154
+ url: "https://example.com/api/mcp",
2155
+ description: "Use product tools through MCP.",
2156
+ },
2157
+ ],
2158
+ },
2159
+ links: [
2160
+ {
2161
+ label: "Support",
2162
+ href: "https://example.com/support",
2163
+ description: "Get help from the product team.",
2164
+ },
2165
+ ],
2166
+ } satisfies GeistdocsAgentReadinessConfig;
2167
+ ```
2168
+
2169
+ ```tsx title="lib/geistdocs/config.tsx"
2170
+ import { agent } from "@/geistdocs";
2171
+
2172
+ export const config = defineConfig({
2173
+ // ...
2174
+ agent,
2175
+ });
2176
+ ```
2177
+
2178
+ ## Keep it honest
2179
+
2180
+ Only list OpenAPI specs, authentication flows, or MCP servers that actually exist. Geistdocs validates new `openApiSpecs` entries and MCP servers rendered by `/.well-known/mcp.json` as absolute `http` or `https` URLs or root-relative paths. Existing `/agents.md` URL fields keep the same URL handling as previous versions. Geistdocs makes product capabilities discoverable, but it does not create APIs or MCP tools for you.
2181
+
2182
+ Use `/agents.md` and `/.well-known/mcp.json` with [llms.txt](/docs/llms-txt), [.md extension](/docs/md), and [Proxy and markdown routes](/docs/proxy) to give agents a complete discovery path.
2183
+
2184
+
2185
+ ---
2186
+
2187
+ ---
2188
+ title: Ask AI
2189
+ description: An AI-powered chat assistant that helps users understand your documentation with context-aware responses
2190
+ type: conceptual
2191
+ summary: An AI-powered chat assistant with context-aware search, persistent history, and suggested prompts for your documentation.
2192
+ url: /docs/ask-ai
2193
+ source: apps/template/content/docs/ask-ai.mdx
2194
+ prerequisites:
2195
+ - /docs/env
2196
+ related:
2197
+ - /docs/open-in-chat
2198
+ - /docs/llms-txt
2199
+ - /docs/configuration
2200
+ ---
2201
+
2202
+ # Ask AI
2203
+
2204
+ The Ask AI feature provides an intelligent chat assistant built directly into your documentation. Users can ask questions about your docs and get instant, context-aware answers powered by AI. The assistant can search through your documentation, understand context, and provide helpful responses.
2205
+
2206
+ Help me configure Ask AI for this Geistdocs site. Check my AI prompt, suggestions, environment variables, and search route, then recommend improvements for the assistant experience.
2207
+
2208
+ ## How it works
2209
+
2210
+ The AI chat assistant is available in two ways:
2211
+
2212
+ ### 1. Per-Page Quick Access
2213
+
2214
+ Each documentation page has an "Ask AI about this page" button in the table of contents sidebar. When clicked, it:
2215
+
2216
+ 1. Opens the chat interface
2217
+ 2. Pre-fills a prompt asking the AI to read the current page
2218
+ 3. Allows users to ask specific questions about that page
2219
+
2220
+ ### 2. Global Chat Interface
2221
+
2222
+ Users can open the chat interface at any time by:
2223
+
2224
+ - Clicking the "Ask AI" button in the navbar
2225
+ - Using the keyboard shortcut: `⌘I` (Mac) or `Ctrl+I` (Windows/Linux)
2226
+
2227
+ Once open, users can:
2228
+
2229
+ - Ask questions about any part of your documentation
2230
+ - Upload files or images for context
2231
+ - View AI-powered search results from your docs
2232
+ - Get step-by-step guidance on complex topics
2233
+
2234
+ ## AI SDK dependency ownership
2235
+
2236
+ Geistdocs Ask AI is built on AI SDK v6. Generated projects install `ai` v6 and `@ai-sdk/react` v3, and `@vercel/geistdocs` owns the chat client, transport, and `createChatRoute` server behavior.
2237
+
2238
+ When a consumer app already uses the AI SDK outside Geistdocs, treat that as app code. Upgrade the app code to the installed AI SDK version or let the package manager install separate versions if needed. Do not fork Geistdocs chat internals or downgrade Ask AI to match unrelated app usage.
2239
+
2240
+ Most projects should not customize the chat transport. If you do customize `DefaultChatTransport.prepareSendMessagesRequest`, preserve `messages` in the returned request body. The AI SDK passes `messages` separately from `body`, and returning a custom `body` replaces the default request body.
2241
+
2242
+ ```ts
2243
+ prepareSendMessagesRequest: ({ body, messages }) => ({
2244
+ body: {
2245
+ ...body,
2246
+ messages,
2247
+ currentRoute: pathname,
2248
+ },
2249
+ });
2250
+ ```
2251
+
2252
+ ## Choose an AI mode
2253
+
2254
+ Ask AI can run in the default AI Gateway mode or through a Vertex-backed proxy.
2255
+
2256
+ ### Default AI Gateway mode
2257
+
2258
+ Use the default mode when the Geistdocs site should call the Vercel AI Gateway directly.
2259
+
2260
+ 1. Leave `GEISTDOCS_CHAT_PROXY_URL` unset.
2261
+ 2. Set `AI_GATEWAY_API_KEY` for local development. Vercel sets this automatically for deployments that have AI Gateway access.
2262
+ 3. Keep `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` set to the site's production host, such as `docs.example.com` or `localhost:3000` for local development.
2263
+
2264
+ In this mode, Geistdocs uses the local `search_docs` tool during the AI SDK `streamText` loop.
2265
+
2266
+ ### Vertex-backed proxy mode
2267
+
2268
+ Use proxy mode when Ask AI should route model requests through a central Vertex-backed service instead of calling AI Gateway from each site.
2269
+
2270
+ 1. Deploy or use the central Geistdocs platform proxy that exposes `POST /vertex`.
2271
+ 2. Configure the Vertex deployment to trust the Geistdocs platform Vercel project with Deployment Protection Trusted Sources.
2272
+ 3. Set `GEISTDOCS_CHAT_PROXY_URL` on the Geistdocs site to the platform proxy URL, including `/vertex`:
2273
+
2274
+ ```txt
2275
+ https://<geistdocs-platform-deployment>/vertex
2276
+ ```
2277
+
2278
+ 4. Leave `GEISTDOCS_CHAT_PROXY_TOKEN` unset unless you are using a custom proxy that requires bearer authentication.
2279
+
2280
+ When `GEISTDOCS_CHAT_PROXY_URL` is set, Geistdocs searches local docs on the first user message, injects the current page and related docs into the final user message, forwards `{ messages, platform: "vercel" }` to the proxy, and streams the AI SDK UI stream response back to the browser.
2281
+
2282
+ The platform proxy forwards a Vercel OIDC token to Vertex in the `x-vercel-trusted-oidc-idp-token` header. The Vertex deployment should validate the caller through Trusted Sources; the Geistdocs site does not need a Vertex API key.
2283
+
2284
+ ## Features
2285
+
2286
+ ### Context-Aware Search
2287
+
2288
+ By default, the AI assistant includes a built-in `search_docs` tool that:
2289
+
2290
+ 1. Searches through your documentation content
2291
+ 2. Finds relevant pages based on the user's question
2292
+ 3. Shows source citations with links to the referenced pages
2293
+ 4. Uses the content to provide accurate, contextual answers
2294
+
2295
+ When `GEISTDOCS_CHAT_PROXY_URL` is set, Geistdocs runs local documentation retrieval on the first user message before forwarding the request to the configured proxy. This gives proxy-backed services access to the current page and related local documentation without requiring them to read the site's source files directly.
2296
+
2297
+ ### Persistent Chat History
2298
+
2299
+ Conversations are automatically saved to the browser's IndexedDB, providing:
2300
+
2301
+ - Chat history that persists across page reloads
2302
+ - Ability to continue previous conversations
2303
+ - Option to start a new chat or clear history
2304
+ - Offline access to past conversations
2305
+
2306
+ ### Interactive Features
2307
+
2308
+ - **Suggestions**: First-time users see suggested questions to get started
2309
+ - **File Upload**: Users can attach files or images for context
2310
+ - **Markdown Support**: Responses are formatted with proper Markdown rendering
2311
+ - **Code Syntax Highlighting**: Code blocks in responses include syntax highlighting
2312
+ - **Reasoning Display**: In development mode, view the AI's reasoning process
2313
+
2314
+ ### Mobile-Responsive
2315
+
2316
+ The chat interface adapts to different screen sizes:
2317
+
2318
+ - **Desktop**: Slides in from the right side as a sidebar panel
2319
+ - **Mobile**: Opens as a bottom drawer.
2320
+
2321
+ ## Configuration
2322
+
2323
+ The environment variables `AI_GATEWAY_API_KEY` and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` must be set for the default AI Gateway mode. Set `GEISTDOCS_CHAT_PROXY_URL` to route Ask AI through a Vertex-backed proxy instead. You can read more in the [Environment Variables](/docs/env) section.
2324
+
2325
+ In default AI Gateway mode, Geistdocs uses `openai/gpt-4.1-mini` via the Vercel AI Gateway. In Vertex-backed proxy mode, the configured proxy controls the upstream model.
2326
+
2327
+ ## Suggested Prompts
2328
+
2329
+ You can customize the initial suggested prompts shown to users. These are configured in the Geistdocs configuration file, which you can read more about in the [Configuration](/docs/configuration) section.
2330
+
2331
+
2332
+ ---
2333
+
2334
+ ---
2335
+ title: Edit on GitHub
2336
+ description: Allow readers to contribute directly by editing documentation pages on GitHub
2337
+ type: integration
2338
+ summary: A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
2339
+ url: /docs/edit-on-github
2340
+ source: apps/template/content/docs/edit-on-github.mdx
2341
+ related:
2342
+ - /docs/configuration
2343
+ ---
2344
+
2345
+ # Edit on GitHub
2346
+
2347
+ The "Edit on GitHub" feature gives readers a direct link to propose documentation changes. This link appears in the table of contents sidebar on every documentation page.
2348
+
2349
+ Help me configure Edit on GitHub for this Geistdocs site. Check the `github` owner and repo in `geistdocs.tsx`, verify the generated edit URL for this page, and tell me how to disable the action if needed.
2350
+
2351
+ ## How it works
2352
+
2353
+ When users click the "Edit this page on GitHub" link, they are taken directly to the source file in your GitHub repository. From there, they can:
2354
+
2355
+ 1. Fork the repository (if they haven't already)
2356
+ 2. Make their edits in the GitHub web editor
2357
+ 3. Submit a pull request with their changes
2358
+
2359
+ This workflow leverages GitHub's built-in editing capabilities, making it straightforward for both technical and non-technical users to contribute.
2360
+
2361
+ ## Configuration
2362
+
2363
+ The Edit on GitHub link is automatically generated based on the `github` object in your `geistdocs.tsx` configuration file. Set the `owner` and `repo` properties to enable this feature:
2364
+
2365
+ ```tsx
2366
+ export const github = {
2367
+ owner: "your-username",
2368
+ repo: "your-repo-name",
2369
+ };
2370
+ ```
2371
+
2372
+ If these values are not set, the link will not appear on your documentation pages.
2373
+
2374
+ ### Generated URL Format
2375
+
2376
+ The link follows this pattern:
2377
+
2378
+ ```
2379
+ https://github.com/{owner}/{repo}/edit/main/content/docs/{file-path}
2380
+ ```
2381
+
2382
+ For example, if your page is located at `content/docs/getting-started.mdx`, the generated link would be:
2383
+
2384
+ ```
2385
+ https://github.com/your-username/your-repo-name/edit/main/content/docs/getting-started.mdx
2386
+ ```
2387
+
2388
+
2389
+ ---
2390
+
2391
+ ---
2392
+ title: Feedback
2393
+ description: Collect user feedback with an interactive emotion-based widget that creates GitHub Issues
2394
+ type: integration
2395
+ summary: An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
2396
+ url: /docs/feedback
2397
+ source: apps/template/content/docs/feedback.mdx
2398
+ prerequisites:
2399
+ - /docs/getting-started
2400
+ related:
2401
+ - /docs/provider
2402
+ - /docs/configuration
2403
+ ---
2404
+
2405
+ # Feedback
2406
+
2407
+ The Feedback feature lets readers share page-level feedback through an interactive widget. Feedback is posted to a centralized GitHub repository as issues so your team can track, label, and respond to user input.
2408
+
2409
+ Help me configure feedback for this Geistdocs project. Check whether feedback is enabled, what `siteId` label is used, and how feedback is sent to the Geistdocs platform and GitHub issues.
2410
+
2411
+ ## How it works
2412
+
2413
+ The feedback widget appears in the table of contents sidebar on every documentation page. When users click "Give feedback", they can:
2414
+
2415
+ 1. Write their feedback message
2416
+ 2. Select an emotion that represents their experience (🤩, 🙂, 😕, 😭)
2417
+ 3. Optionally provide their name and email
2418
+ 4. Submit their feedback
2419
+
2420
+ ### Feedback Workflow
2421
+
2422
+ When feedback is submitted:
2423
+
2424
+ 1. The feedback is validated against a JSON schema
2425
+ 2. A new GitHub Issue is created in the configured feedback repository
2426
+ 3. Labels are automatically applied based on the emotion, topic, and other metadata
2427
+ 4. User details and metadata are formatted into a structured markdown table
2428
+
2429
+ Each piece of feedback creates a separate issue, allowing for individual tracking and resolution.
2430
+
2431
+ ## Feedback Schema
2432
+
2433
+ The API accepts the following fields:
2434
+
2435
+ | Field | Type | Required | Max Length | Description |
2436
+ | --------- | ------ | -------- | ---------- | ------------------------------------- |
2437
+ | `note` | string | Yes | 16,384 | The feedback message |
2438
+ | `url` | string | No | 1,024 | Page URL where feedback was submitted |
2439
+ | `emotion` | string | No | 1 | Emoji representing user sentiment |
2440
+ | `topic` | string | No | 1,024 | Feedback topic/category |
2441
+ | `name` | string | No | 1,024 | User's name |
2442
+ | `email` | string | No | 1,024 | User's email |
2443
+ | `ua` | string | No | 256 | User agent string |
2444
+ | `label` | string | No | 64 | Custom label for the issue |
2445
+ | `thumbs` | string | No | 4 | Thumbs up/down indicator |
2446
+ | `reason` | string | No | 10 | Reason for thumbs down |
2447
+ | `plan` | string | No | 10 | User's plan type |
2448
+
2449
+ Additional fields are captured as metadata and displayed in the issue body.
2450
+
2451
+ ## Features
2452
+
2453
+ ### Automatic Labeling
2454
+
2455
+ Issues are automatically labeled based on:
2456
+
2457
+ - **Emotion**: `emotion-amazed`, `emotion-happy`, `emotion-sad`, `emotion-cry`
2458
+ - **Topic**: `topic-{topic-name}`
2459
+ - **Plan**: `{plan}-plan`
2460
+ - **Thumbs**: `thumbs-up`, `thumbs-down`
2461
+ - **Reason**: `reason-{reason}` (for thumbs down)
2462
+ - **Custom labels**: Any label passed via the `label` field
2463
+ - **Default labels**: `unresolved`, `vercel-site`
2464
+
2465
+ ### Structured Issue Body
2466
+
2467
+ Each issue includes a formatted markdown body with:
2468
+
2469
+ - The feedback note
2470
+ - URL where feedback was submitted
2471
+ - User details table (email, context, IP, user agent)
2472
+ - Metadata table for any additional fields
2473
+
2474
+ ### Metadata Support
2475
+
2476
+ Pass any additional fields in the request body, and they are captured as metadata and displayed in a separate table in the issue. This allows you to include:
2477
+
2478
+ - User IDs
2479
+ - Feature flags
2480
+ - Experiment groups
2481
+ - Custom tracking data
2482
+
2483
+
2484
+ ---
2485
+
2486
+ ---
2487
+ title: Internationalization
2488
+ description: Add multi-language support to your documentation site
2489
+ type: guide
2490
+ summary: Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
2491
+ url: /docs/internationalization
2492
+ source: apps/template/content/docs/internationalization.mdx
2493
+ prerequisites:
2494
+ - /docs/getting-started
2495
+ related:
2496
+ - /docs/configuration
2497
+ ---
2498
+
2499
+ # Internationalization
2500
+
2501
+ Geistdocs supports internationalization (i18n) out of the box using Fumadocs' language-aware routing. You can serve documentation in multiple languages with automatic translation via the Geistdocs CLI.
2502
+
2503
+ Help me add a new language to this Geistdocs project. Update `translations` in `geistdocs.tsx`, run the Geistdocs translate command for `content/docs`, and explain how localized routes are generated.
2504
+
2505
+ ## How it works
2506
+
2507
+ The i18n system uses dynamic routing with a `[lang]` URL segment. The default language (English) doesn't show in URLs, while other languages get a prefix:
2508
+
2509
+ - `/docs/getting-started` - English (default)
2510
+ - `/cn/docs/getting-started` - Chinese
2511
+
2512
+ Users can switch languages using the language selector in the navigation bar.
2513
+
2514
+ ## Translating Content
2515
+
2516
+ Use the Geistdocs CLI to automatically translate your MDX files:
2517
+
2518
+ ```bash
2519
+ pnpm translate
2520
+ ```
2521
+
2522
+ The CLI reads your target locales from `geistdocs.tsx`. If no locales are found in the config, you'll be prompted to enter them manually.
2523
+
2524
+ Translations are generated using the Geistdocs platform and saved alongside your original file with the locale suffix (e.g., `introduction.cn.mdx`).
2525
+
2526
+ ### Command Options
2527
+
2528
+ You can pass options directly to customize the translation behavior:
2529
+
2530
+ ```bash
2531
+ # Translate all MDX files (uses default pattern)
2532
+ pnpm translate
2533
+
2534
+ # Translate files matching a specific glob pattern
2535
+ pnpm translate "content/docs/**/*.mdx"
2536
+
2537
+ # Use a custom config file
2538
+ pnpm translate "content/**/*.mdx" --config custom-config.tsx
2539
+
2540
+ # Use a custom translation API URL
2541
+ pnpm translate --url "https://custom-api.example.com/translate"
2542
+ ```
2543
+
2544
+ | Option | Description |
2545
+ | ----------- | -------------------------------------------------------- |
2546
+ | `--config` | Path to config file with translations (default: `geistdocs.tsx`) |
2547
+ | `--url` | Custom translation API URL (can also use `GEISTDOCS_TRANSLATE_URL` env var) |
2548
+
2549
+ Pass the glob pattern as the command argument. If you omit it, Geistdocs uses `content/docs/**/*.mdx`.
2550
+
2551
+ The CLI automatically excludes files that already have a locale suffix (e.g., `getting-started.cn.mdx`) to avoid translating already-translated content.
2552
+
2553
+ ### Batch Processing
2554
+
2555
+ When translating multiple files, the CLI automatically batches them into groups of 10. Progress is displayed as each batch completes, and a 1-second delay is added between batches to avoid rate limiting.
2556
+
2557
+ ## Configuration
2558
+
2559
+ Configure supported languages in `geistdocs.tsx`:
2560
+
2561
+ ```typescript title="geistdocs.tsx"
2562
+ export const translations = {
2563
+ en: {
2564
+ displayName: "English",
2565
+ },
2566
+ cn: {
2567
+ displayName: "中文",
2568
+ search: "搜尋文檔",
2569
+ },
2570
+ };
2571
+ ```
2572
+
2573
+ The first locale in the `translations` object is treated as your default/source language and is excluded from translation targets.
2574
+
2575
+ ### Adding a New Language
2576
+
2577
+ To add a new language:
2578
+
2579
+ 1. Add a new key to the `translations` object with the language code
2580
+ 2. Add translations for UI elements like `displayName` and `search`
2581
+ 3. Run `pnpm translate "content/**/*.mdx"` to generate translated content
2582
+
2583
+ The language selector will automatically include your new language.
2584
+
2585
+ ## Content Organization
2586
+
2587
+ Translated files are saved alongside the original with a locale suffix:
2588
+
2589
+ ```
2590
+ content/docs/
2591
+ ├── getting-started.mdx # English (default)
2592
+ ├── getting-started.cn.mdx # Chinese
2593
+ ├── getting-started.fr.mdx # French
2594
+ └── getting-started.es.mdx # Spanish
2595
+ ```
2596
+
2597
+ Fumadocs automatically serves the correct file based on the URL path.
2598
+
2599
+ ## Translating UI Elements
2600
+
2601
+ The `translations` object in `geistdocs.tsx` controls UI text like search placeholders, navigation labels, and error messages. Add translations for each language you support.
2602
+
2603
+ If you don't provide a translation for a specific element, it falls back to English.
2604
+
2605
+ ## Language Detection
2606
+
2607
+ The language is determined by the URL path. There's no automatic detection based on browser settings - users must explicitly choose their language using the language selector.
2608
+
2609
+ This approach gives users full control and ensures they see the language they expect.
2610
+
2611
+
2612
+ ---
2613
+
2614
+ ---
2615
+ title: llms.txt
2616
+ description: A single file containing all your documentation in plain text for AI consumption
2617
+ type: conceptual
2618
+ summary: A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
2619
+ url: /docs/llms-txt
2620
+ source: apps/template/content/docs/llms-txt.mdx
2621
+ related:
2622
+ - /docs/agent-readiness
2623
+ - /docs/md
2624
+ - /docs/ask-ai
2625
+ - /docs/proxy
2626
+ ---
2627
+
2628
+ # llms.txt
2629
+
2630
+ Geistdocs implements the [llms.txt standard](https://llmstxt.org/), a convention for exposing documentation as one AI-readable text file. Language models and coding agents can use `/llms.txt` to retrieve broad documentation context.
2631
+
2632
+ Help me verify this Geistdocs site's AI-readable docs. Check `/llms.txt` and a few `.mdx` page URLs, then explain whether an AI assistant can retrieve the full documentation context.
2633
+
2634
+ ## What it is
2635
+
2636
+ The `/llms.txt` endpoint returns all configured documentation pages as Markdown in a single response. Each page is separated by blank lines so AI tools can parse the complete documentation set. When agent metadata is configured, page-level Markdown also links agents to `/agents.md` for API and MCP discovery.
2637
+
2638
+ ### Access
2639
+
2640
+ ```
2641
+ https://yourdomain.com/llms.txt
2642
+ ```
2643
+
2644
+ Returns all documentation pages concatenated together as Markdown.
2645
+
2646
+ ## How it works
2647
+
2648
+ The package route helper:
2649
+
2650
+ 1. Fetches pages from one or more source bundles.
2651
+ 2. Processes each page to extract clean Markdown.
2652
+ 3. Combines the pages into a single response.
2653
+ 4. Returns the response as `text/markdown`.
2654
+
2655
+ Pages are joined with double newlines (`\n\n`) for clear separation.
2656
+
2657
+ ## Use cases
2658
+
2659
+ This feature enables:
2660
+
2661
+ - **AI Training** - Provide your docs as context for AI assistants
2662
+ - **Search Indexing** - Feed your entire documentation to search systems
2663
+ - **Content Analysis** - Analyze patterns and content across all docs
2664
+ - **Bulk Processing** - Process all documentation at once
2665
+ - **LLM Context** - Give language models complete documentation context
2666
+
2667
+ ## Configure sources
2668
+
2669
+ Generated projects use one documentation source:
2670
+
2671
+ ```ts title="app/[lang]/llms.txt/route.ts"
2672
+ import { createLlmsRoute } from "@vercel/geistdocs/routes/llms";
2673
+ import { geistdocsSource } from "@/lib/geistdocs/source";
2674
+
2675
+ export const { GET, revalidate } = createLlmsRoute({
2676
+ source: geistdocsSource,
2677
+ });
2678
+ ```
2679
+
2680
+ Sites with multiple content sections or versions can pass `sources`:
2681
+
2682
+ ```ts title="app/[lang]/llms.txt/route.ts"
2683
+ export const { GET, revalidate } = createLlmsRoute({
2684
+ sources: [docsSource, cookbookSource],
2685
+ });
2686
+ ```
2687
+
2688
+ Use `filterPage` to exclude pages from `/llms.txt`, such as internal or preview-only docs:
2689
+
2690
+ ```ts title="app/[lang]/llms.txt/route.ts"
2691
+ export const { GET, revalidate } = createLlmsRoute({
2692
+ source: geistdocsSource,
2693
+ filterPage: (page) => !page.url.includes("/internal"),
2694
+ });
2695
+ ```
2696
+
2697
+ ## The llms.txt standard
2698
+
2699
+ The llms.txt standard is a simple convention that makes documentation more accessible to AI tools. It's similar in spirit to `robots.txt` but designed for language models instead of search crawlers.
2700
+
2701
+ Learn more at [llmstxt.org](https://llmstxt.org/)
2702
+
2703
+
2704
+ ---
2705
+
2706
+ ---
2707
+ title: Open in Chat
2708
+ description: Allow users to continue conversations in their preferred AI chat platform with a single click
2709
+ type: conceptual
2710
+ summary: Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
2711
+ url: /docs/open-in-chat
2712
+ source: apps/template/content/docs/open-in-chat.mdx
2713
+ related:
2714
+ - /docs/ask-ai
2715
+ - /docs/env
2716
+ ---
2717
+
2718
+ # Open in Chat
2719
+
2720
+ The "Open in Chat" feature enables users to seamlessly transfer documentation context to their preferred AI assistant. With a single click, users can open the current page in external AI chat platforms like ChatGPT, Claude, v0, Cursor, and more.
2721
+
2722
+ Help me test Open in Chat for this Geistdocs site. Verify that page URLs resolve correctly, markdown endpoints work, and each configured AI platform receives useful context.
2723
+
2724
+ ## How it works
2725
+
2726
+ On every documentation page, users will find an "Open in chat" button in the table of contents sidebar. When clicked, a menu appears with options to open the page in various AI platforms:
2727
+
2728
+ 1. User clicks "Open in chat"
2729
+ 2. A dropdown menu shows available platforms
2730
+ 3. User selects their preferred AI assistant
2731
+ 4. The platform opens with a pre-filled prompt containing the page URL and context
2732
+
2733
+ The prompt automatically includes:
2734
+
2735
+ ```
2736
+ Read this page, I want to ask questions about it. [URL]
2737
+ ```
2738
+
2739
+ This allows the AI assistant to fetch and understand the page content before answering user questions.
2740
+
2741
+ ## Supported Platforms
2742
+
2743
+ The feature integrates with multiple popular AI platforms:
2744
+
2745
+ ### Code & Development Tools
2746
+
2747
+ - **[Cursor](https://cursor.sh/)** - AI-powered code editor
2748
+ - **[v0](https://v0.dev/)** - Vercel's AI interface design tool
2749
+
2750
+ ### General AI Assistants
2751
+
2752
+ - **[ChatGPT](https://chat.openai.com/)** - OpenAI's conversational AI
2753
+ - **[Claude](https://claude.ai/)** - Anthropic's AI assistant
2754
+ - **[T3](https://t3.gg/)** - T3 Stack AI assistant
2755
+ - **[Scira](https://scira.app/)** - AI-powered documentation assistant
2756
+
2757
+ ## Configuration
2758
+
2759
+ The environment variable `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` must be set, which you can read more about in the [Environment Variables](/docs/env) section.
2760
+
2761
+ ## User Experience
2762
+
2763
+ ### Desktop Experience
2764
+
2765
+ The "Open in chat" button appears in the table of contents sidebar with an external link icon. Clicking it reveals a dropdown menu with all available platforms.
2766
+
2767
+ ### Platform-Specific Behavior
2768
+
2769
+ Each platform has its own integration:
2770
+
2771
+ - **Browser-based platforms** (ChatGPT, Claude, v0): Open in a new browser tab with the prompt pre-filled
2772
+ - **Desktop applications** (Cursor): Open using a custom URL scheme that launches the application
2773
+ - **Specialized tools** (T3, Scira): Open with platform-specific parameters and context
2774
+
2775
+ ## Outcomes
2776
+
2777
+ ### For Users
2778
+
2779
+ 1. **Context transfer**: Users do not need to manually copy URLs or switch contexts.
2780
+ 2. **Consistent starting point**: Each AI platform receives the same page context.
2781
+ 3. **Tool choice**: Users can open the AI platform they prefer.
2782
+
2783
+ ### For Documentation Authors
2784
+
2785
+ 1. **More support paths**: Users can ask follow-up questions about a page.
2786
+ 2. **Lower support load**: AI assistants can answer common documentation questions.
2787
+ 3. **Platform flexibility**: Teams can support different AI preferences.
2788
+
2789
+
2790
+ ---
2791
+
2792
+ ---
2793
+ title: RSS
2794
+ description: Keep users updated with an automatically generated RSS feed for your documentation
2795
+ type: conceptual
2796
+ summary: An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
2797
+ url: /docs/rss
2798
+ source: apps/template/content/docs/rss.mdx
2799
+ related:
2800
+ - /docs/env
2801
+ - /docs/configuration
2802
+ ---
2803
+
2804
+ # RSS
2805
+
2806
+ The RSS feature provides an automatically generated RSS 2.0 feed for your documentation. This allows users to subscribe to updates and stay informed when new content is published or existing pages are modified.
2807
+
2808
+ Help me verify the RSS feed for this Geistdocs site. Check the `/rss.xml` route, confirm the production URL environment variable is set, and explain how page metadata affects feed items.
2809
+
2810
+ ## How it works
2811
+
2812
+ Geistdocs automatically generates an RSS feed that includes:
2813
+
2814
+ - All published documentation pages
2815
+ - Page titles and descriptions
2816
+ - Direct links to each page
2817
+ - Last modified dates
2818
+ - Author information
2819
+
2820
+ The feed is regenerated on each request, ensuring subscribers always receive the most current information about your documentation.
2821
+
2822
+ ## Accessing the Feed
2823
+
2824
+ The RSS feed is available at:
2825
+
2826
+ ```
2827
+ https://your-domain.com/rss.xml
2828
+ ```
2829
+
2830
+ Users can subscribe to this URL using:
2831
+
2832
+ - RSS readers (Feedly, Inoreader, NewsBlur)
2833
+ - Email services (Blogtrottr, Kill the Newsletter)
2834
+ - Browser extensions
2835
+ - News aggregators
2836
+
2837
+ ### RSS Button
2838
+
2839
+ An RSS button appears in the navigation bar so readers can discover and subscribe to your feed. Clicking the button opens the RSS XML in a new tab.
2840
+
2841
+ ## Feed Format
2842
+
2843
+ The RSS feed follows the RSS 2.0 specification and includes:
2844
+
2845
+ ### Channel Metadata
2846
+
2847
+ ```xml
2848
+ <channel>
2849
+ <title>Your Documentation Title</title>
2850
+ <link>https://your-domain.com</link>
2851
+ <language>en</language>
2852
+ <image>https://your-domain.com/banner.png</image>
2853
+ <copyright>All rights reserved [Year], [Your Organization]</copyright>
2854
+ </channel>
2855
+ ```
2856
+
2857
+ ### Item Format
2858
+
2859
+ Each documentation page appears as an item:
2860
+
2861
+ ```xml
2862
+ <item>
2863
+ <guid>page-url</guid>
2864
+ <title>Page Title</title>
2865
+ <description>Page description</description>
2866
+ <link>https://your-domain.com/docs/page-url</link>
2867
+ <pubDate>Thu, 12 Nov 2025 00:00:00 GMT</pubDate>
2868
+ <author>
2869
+ <name>Your Organization</name>
2870
+ </author>
2871
+ </item>
2872
+ ```
2873
+
2874
+ ## Configuration
2875
+
2876
+ The RSS feed requires the `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` environment variable to be set, which you can read more about in the [Environment Variables](/docs/env) section.
2877
+
2878
+ It also requires a `title` exported from the Geistdocs configuration file, which you can read more about in the [Configuration](/docs/configuration) section.
2879
+
2880
+ ## Features
2881
+
2882
+ ### Automatic Updates
2883
+
2884
+ The feed automatically includes:
2885
+
2886
+ - Newly created pages
2887
+ - Updated page content (using last modified dates)
2888
+ - Changed titles or descriptions
2889
+ - All pages from your documentation source
2890
+
2891
+ ### Last Modified Dates
2892
+
2893
+ Pages use their `lastModified` frontmatter field or fall back to the current date:
2894
+
2895
+ ```mdx title="content/docs/example.mdx"
2896
+ ---
2897
+ title: Example Page
2898
+ description: An example documentation page
2899
+ lastModified: 2025-11-12
2900
+ ---
2901
+ ```
2902
+
2903
+
2904
+ ---
2905
+
2906
+ ---
2907
+ title: Theme-Aware Image
2908
+ description: Display different images based on the user's light or dark theme preference
2909
+ type: reference
2910
+ summary: A component that swaps images based on the active theme, built on top of Next.js Image.
2911
+ url: /docs/theme-aware-image
2912
+ source: apps/template/content/docs/theme-aware-image.mdx
2913
+ prerequisites:
2914
+ - /docs/getting-started
2915
+ - /docs/provider
2916
+ related:
2917
+ - /docs/syntax
2918
+ - /docs/configuration
2919
+ ---
2920
+
2921
+ # Theme-Aware Image
2922
+
2923
+ The `ThemeAwareImage` component renders different images depending on whether the user is viewing your documentation in light or dark mode. It extends the Next.js `Image` component, so you get all the same optimization benefits like lazy loading, responsive sizing, and format conversion.
2924
+
2925
+ Help me add a theme-aware image to a Geistdocs MDX page. Create a usage example with light and dark image sources, alt text, width, and height, then explain where to place the image files.
2926
+
2927
+ ## Usage
2928
+
2929
+ Import the component and pass a `src` object with `light` and `dark` variants:
2930
+
2931
+ ```tsx
2932
+ import { ThemeAwareImage } from "@vercel/geistdocs/components/theme-aware-image";
2933
+
2934
+ <ThemeAwareImage
2935
+ src={{
2936
+ light: "/images/diagram-light.png",
2937
+ dark: "/images/diagram-dark.png",
2938
+ }}
2939
+ alt="Architecture diagram"
2940
+ width={800}
2941
+ height={400}
2942
+ />
2943
+ ```
2944
+
2945
+ The component reads the current theme from `next-themes` and resolves the correct image source automatically. All standard Next.js `Image` props (such as `width`, `height`, `alt`, `priority`, and `className`) are supported.
2946
+
2947
+ ## How it works
2948
+
2949
+ `ThemeAwareImage` uses the `resolvedTheme` value from the `useTheme` hook provided by `next-themes`. This ensures it responds to the actual rendered theme, even when the user's preference is set to "system".
2950
+
2951
+ - When `resolvedTheme` is `"dark"`, the `src.dark` image is displayed.
2952
+ - Otherwise, the `src.light` image is used.
2953
+
2954
+ Because this component relies on client-side theme detection, it is a client component (`"use client"`).
2955
+
2956
+ ## Props
2957
+
2958
+ | Prop | Type | Description |
2959
+ | --- | --- | --- |
2960
+ | `src` | `{ light: ImageProps["src"]; dark: ImageProps["src"] }` | An object containing the light and dark image sources |
2961
+ | `alt` | `string` | Accessible alt text for the image |
2962
+ | `width` | `number` | The width of the image in pixels |
2963
+ | `height` | `number` | The height of the image in pixels |
2964
+ | `...rest` | `ImageProps` | Any additional props supported by the Next.js `Image` component |
2965
+