@vercel/geistdocs 1.3.1 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli/index.js +1 -1
- package/dist/config.d.ts +6 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/routes/agents.d.ts.map +1 -1
- package/dist/routes/agents.js +14 -29
- package/dist/routes/discovery.d.ts +14 -0
- package/dist/routes/discovery.d.ts.map +1 -0
- package/dist/routes/discovery.js +74 -0
- package/dist/routes/mcp.d.ts +26 -0
- package/dist/routes/mcp.d.ts.map +1 -0
- package/dist/routes/mcp.js +31 -0
- package/dist/source.d.ts +1 -1
- package/dist/source.d.ts.map +1 -1
- package/dist/source.js +4 -1
- package/docs/agents.md +44 -0
- package/docs/llms.txt +2965 -0
- package/docs/manifest.json +194 -0
- package/docs/pages/agent-readiness.md +141 -0
- package/docs/pages/ask-ai.md +143 -0
- package/docs/pages/configuration.md +278 -0
- package/docs/pages/deployment.md +53 -0
- package/docs/pages/edit-on-github.md +53 -0
- package/docs/pages/env.md +62 -0
- package/docs/pages/feedback.md +91 -0
- package/docs/pages/getting-started.md +116 -0
- package/docs/pages/index.md +99 -0
- package/docs/pages/internationalization.md +124 -0
- package/docs/pages/llms-txt.md +88 -0
- package/docs/pages/md.md +84 -0
- package/docs/pages/migration.md +376 -0
- package/docs/pages/open-in-chat.md +82 -0
- package/docs/pages/provider.md +76 -0
- package/docs/pages/proxy.md +180 -0
- package/docs/pages/rss.md +110 -0
- package/docs/pages/syntax.md +413 -0
- package/docs/pages/theme-aware-image.md +59 -0
- package/docs/pages/versioned-docs.md +230 -0
- package/docs/sitemap.md +25 -0
- package/package.json +12 -2
- package/template/AGENTS.md +10 -3
- package/template/app/[lang]/.well-known/mcp.json/route.ts +8 -0
- package/template/content/docs/agent-readiness.mdx +44 -8
- package/template/content/docs/configuration.mdx +1 -0
- package/template/content/docs/index.mdx +1 -1
- package/template/content/docs/llms-txt.mdx +1 -1
- package/template/content/docs/migration.mdx +12 -2
- 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.0.
|
|
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 ``:
|
|
1134
|
+
|
|
1135
|
+
```md
|
|
1136
|
+

|
|
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
|
+
|