@vercel/geistdocs 2.14.5 → 2.14.7-canary.6ce58a6
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/assets/icons/icon-share.d.ts +13 -0
- package/dist/assets/icons/icon-share.d.ts.map +1 -0
- package/dist/assets/icons/icon-share.js +12 -0
- package/dist/assets/icons/index.d.ts +1 -0
- package/dist/assets/icons/index.d.ts.map +1 -1
- package/dist/assets/icons/index.js +1 -0
- package/dist/cli/index.js +5 -5
- package/dist/config.d.ts +38 -3
- package/dist/config.d.ts.map +1 -1
- package/dist/controls.d.ts +3 -40
- package/dist/controls.d.ts.map +1 -1
- package/dist/controls.js +5 -96
- package/dist/internal/chat/share-chat.d.ts +7 -0
- package/dist/internal/chat/share-chat.d.ts.map +1 -0
- package/dist/internal/chat/share-chat.js +76 -0
- package/dist/internal/chat/sharing.d.ts +24 -0
- package/dist/internal/chat/sharing.d.ts.map +1 -0
- package/dist/internal/chat/sharing.js +117 -0
- package/dist/internal/chat/shell.d.ts.map +1 -1
- package/dist/internal/chat/shell.js +2 -1
- package/dist/internal/chat-retrieval.d.ts +10 -9
- package/dist/internal/chat-retrieval.d.ts.map +1 -1
- package/dist/internal/chat-retrieval.js +32 -68
- package/dist/internal/controls-client.d.ts +40 -0
- package/dist/internal/controls-client.d.ts.map +1 -0
- package/dist/internal/controls-client.js +87 -0
- package/dist/internal/language-selector.d.ts +2 -0
- package/dist/internal/language-selector.d.ts.map +1 -0
- package/dist/internal/language-selector.js +12 -0
- package/dist/internal/mixedbread-store.d.ts +53 -0
- package/dist/internal/mixedbread-store.d.ts.map +1 -0
- package/dist/internal/mixedbread-store.js +129 -0
- package/dist/internal/navbar/mobile-menu.js +1 -1
- package/dist/internal/page-action-options.d.ts +37 -0
- package/dist/internal/page-action-options.d.ts.map +1 -0
- package/dist/internal/page-action-options.js +39 -0
- package/dist/internal/page-actions-client.d.ts +1 -31
- package/dist/internal/page-actions-client.d.ts.map +1 -1
- package/dist/internal/page-actions-client.js +5 -103
- package/dist/internal/page-actions-gate.d.ts +3 -0
- package/dist/internal/page-actions-gate.d.ts.map +1 -0
- package/dist/internal/page-actions-gate.js +15 -0
- package/dist/internal/provider-client.d.ts.map +1 -1
- package/dist/internal/provider-client.js +26 -1
- package/dist/internal/relative-docs-link.d.ts +7 -0
- package/dist/internal/relative-docs-link.d.ts.map +1 -0
- package/dist/internal/relative-docs-link.js +22 -0
- package/dist/internal/sidebar.d.ts.map +1 -1
- package/dist/internal/sidebar.js +1 -1
- package/dist/internal/toc-actions-client.d.ts +9 -0
- package/dist/internal/toc-actions-client.d.ts.map +1 -0
- package/dist/internal/toc-actions-client.js +78 -0
- package/dist/mdx.d.ts.map +1 -1
- package/dist/mdx.js +5 -2
- package/dist/navbar.js +1 -1
- package/dist/pages/changelog.js +1 -1
- package/dist/pages/docs.d.ts.map +1 -1
- package/dist/pages/docs.js +4 -3
- package/dist/routes/chat.d.ts +4 -4
- package/dist/routes/chat.d.ts.map +1 -1
- package/dist/routes/chat.js +19 -34
- package/dist/routes/openapi.d.ts.map +1 -1
- package/dist/routes/openapi.js +13 -5
- package/dist/routes/search-export.d.ts +1 -1
- package/dist/routes/search-export.d.ts.map +1 -1
- package/dist/routes/search-export.js +5 -2
- package/dist/routes/search.d.ts +10 -2
- package/dist/routes/search.d.ts.map +1 -1
- package/dist/routes/search.js +215 -55
- package/docs/agents.md +3 -3
- package/docs/llms.txt +237 -32
- package/docs/manifest.json +5 -5
- package/docs/pages/ask-ai.md +17 -1
- package/docs/pages/configuration.md +33 -3
- package/docs/pages/env.md +5 -5
- package/docs/pages/index.md +1 -1
- package/docs/pages/llms-txt.md +1 -1
- package/docs/pages/mixedbread-retrieval.md +174 -18
- package/docs/pages/provider.md +3 -0
- package/docs/sitemap.md +2 -2
- package/package.json +6 -6
- package/template/.env.example +1 -0
- package/template/AGENTS.md +11 -7
- package/template/content/docs/ask-ai.mdx +17 -1
- package/template/content/docs/configuration.mdx +33 -3
- package/template/content/docs/env.mdx +5 -5
- package/template/content/docs/index.mdx +1 -1
- package/template/content/docs/llms-txt.mdx +1 -1
- package/template/content/docs/mixedbread-retrieval.mdx +174 -18
- package/template/content/docs/provider.mdx +3 -0
- package/template/geistdocs.tsx +6 -1
- package/template/lib/geistdocs/config.tsx +2 -0
- package/template/package.json +1 -1
|
@@ -50,7 +50,10 @@ Read [Configure sidebar navigation](/docs/guides/nested-navigation) for page ord
|
|
|
50
50
|
The root `geistdocs.tsx` file is the primary configuration surface:
|
|
51
51
|
|
|
52
52
|
```tsx title="geistdocs.tsx"
|
|
53
|
-
import type {
|
|
53
|
+
import type {
|
|
54
|
+
GeistdocsNavbarBrand,
|
|
55
|
+
GeistdocsSearchConfig,
|
|
56
|
+
} from "@vercel/geistdocs/config";
|
|
54
57
|
|
|
55
58
|
export const navbarBrand: GeistdocsNavbarBrand = "vercel";
|
|
56
59
|
|
|
@@ -89,6 +92,8 @@ export const translations = {
|
|
|
89
92
|
en: { displayName: "English" },
|
|
90
93
|
};
|
|
91
94
|
|
|
95
|
+
export const search = {} satisfies GeistdocsSearchConfig;
|
|
96
|
+
|
|
92
97
|
export const basePath: string | undefined = undefined;
|
|
93
98
|
export const siteId: string | undefined = undefined;
|
|
94
99
|
```
|
|
@@ -157,6 +162,7 @@ import {
|
|
|
157
162
|
nav,
|
|
158
163
|
navbarBrand,
|
|
159
164
|
prompt,
|
|
165
|
+
search,
|
|
160
166
|
siteId,
|
|
161
167
|
suggestions,
|
|
162
168
|
title,
|
|
@@ -172,6 +178,7 @@ export const config = defineConfig({
|
|
|
172
178
|
nav,
|
|
173
179
|
navbarBrand,
|
|
174
180
|
basePath,
|
|
181
|
+
search,
|
|
175
182
|
siteId,
|
|
176
183
|
translations,
|
|
177
184
|
ai: {
|
|
@@ -208,7 +215,7 @@ export const config = defineConfig({
|
|
|
208
215
|
});
|
|
209
216
|
```
|
|
210
217
|
|
|
211
|
-
The `ai` config accepts `retrieval: "mixedbread"` to use semantic documentation retrieval and `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
|
|
218
|
+
The `ai` config accepts `retrieval: "mixedbread"` to use semantic documentation retrieval for Ask AI and `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
|
|
212
219
|
|
|
213
220
|
```tsx title="geistdocs.tsx"
|
|
214
221
|
export const ai = {
|
|
@@ -231,6 +238,7 @@ The `ai` config also controls the chat panel and its route:
|
|
|
231
238
|
| `suggestions` | `(string \| { text: string; icon?: ReactNode })[]` | `[]` | Suggested prompts. The first four distinct prompts are shown, and strings render without an icon. |
|
|
232
239
|
| `history.retentionDays` | `number` | `30` | Days a stored conversation is kept after its most recent message. `0` stores no history, and `Infinity` never expires it. |
|
|
233
240
|
| `messageFeedback` | `boolean` | `false` | Show thumbs up and thumbs down buttons on finished answers and send votes to the Geistdocs feedback service. |
|
|
241
|
+
| `share` | `GeistdocsAIShareConfig` | `undefined` | Show a Share chat action backed by your persistence endpoint and public shared-conversation route. |
|
|
234
242
|
| `toolLabels` | `Record<string, string>` | `{}` | Activity label shown while a named tool runs, such as `{ web_search: "Searching..." }`. Other tools show `Running <tool name>...`. |
|
|
235
243
|
|
|
236
244
|
```tsx title="geistdocs.tsx"
|
|
@@ -239,13 +247,35 @@ export const ai = {
|
|
|
239
247
|
title: "Ask Acme AI",
|
|
240
248
|
history: { retentionDays: 7 },
|
|
241
249
|
messageFeedback: true,
|
|
250
|
+
share: {
|
|
251
|
+
endpoint: "/api/ai-chat/share",
|
|
252
|
+
path: "/ai-chat",
|
|
253
|
+
},
|
|
242
254
|
};
|
|
243
255
|
```
|
|
244
256
|
|
|
245
|
-
|
|
257
|
+
The endpoint receives `{ messages, hostPath, summary? }` and must return `{ shareId }`. The public route at `path/<shareId>` must display the saved conversation. Both paths are app-local; Geistdocs adds `basePath` automatically. See [Share a conversation](/docs/ask-ai#share-a-conversation) for the full contract.
|
|
258
|
+
|
|
259
|
+
See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication, for moving the chat route adapter when you set `endpoint`, for what a `messageFeedback` vote sends, and for matching a production Vertex or eve setup with `toolLabels` and the server-only `createChatRoute` options. Read [Improve Ask AI and site search with Mixedbread](/docs/mixedbread-retrieval) before enabling semantic retrieval.
|
|
246
260
|
|
|
247
261
|
Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
|
|
248
262
|
|
|
263
|
+
### Choose the site search provider
|
|
264
|
+
|
|
265
|
+
The `search` export selects the index behind the search dialog, `GET /api/search`, and the MCP `search_docs` tool. `provider` accepts `"local"`, the default, or `"mixedbread"`:
|
|
266
|
+
|
|
267
|
+
```tsx title="geistdocs.tsx"
|
|
268
|
+
import type { GeistdocsSearchConfig } from "@vercel/geistdocs/config";
|
|
269
|
+
|
|
270
|
+
export const search = {
|
|
271
|
+
provider: "mixedbread",
|
|
272
|
+
} satisfies GeistdocsSearchConfig;
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
`"mixedbread"` ranks results with the site's Mixedbread Store and renders every result from the running deployment. It needs a non-empty `siteId` and the server-only `MXBAI_API_KEY` and `MXBAI_STORE_ID` variables. Without them, or when a Mixedbread request fails, the search route answers from the local index. `search.provider` and `ai.retrieval` are independent, and `search.enabled` keeps its existing meaning.
|
|
276
|
+
|
|
277
|
+
The generated `lib/geistdocs/config.tsx` forwards `search` to `defineConfig`. A site created before this release adds the `search` export and the forward once. Without the forward, search stays local with no error. Read [Improve Ask AI and site search with Mixedbread](/docs/mixedbread-retrieval#use-mixedbread-for-site-search) for the full setup.
|
|
278
|
+
|
|
249
279
|
## Single-language sites
|
|
250
280
|
|
|
251
281
|
A site with one language can drop the `[lang]` route segment by setting `singleLanguage: true` in `defineConfig`. Routes then live directly under `app/`, the proxy skips locale rewrites, and route factories resolve every request to `defaultLanguage`. `translations` may only list `defaultLanguage`. Public URLs, `.md` routes, `llms.txt`, and `agents.md` keep their paths.
|
package/docs/pages/env.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
title: Environment Variables
|
|
3
3
|
description: Learn about the environment variables used in Geistdocs
|
|
4
4
|
type: reference
|
|
5
|
-
summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, eve agent session cookies, and production URL configuration.
|
|
5
|
+
summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval for Ask AI and site search, proxy mode, eve agent session cookies, and production URL configuration.
|
|
6
6
|
url: /docs/env
|
|
7
7
|
source: apps/template/content/docs/env.mdx
|
|
8
8
|
prerequisites:
|
|
@@ -14,7 +14,7 @@ related:
|
|
|
14
14
|
|
|
15
15
|
# Environment Variables
|
|
16
16
|
|
|
17
|
-
Geistdocs uses environment variables to configure Ask AI, optional Mixedbread retrieval, optional Vertex-backed proxy mode, eve agent session cookie signing, and production URL behavior.
|
|
17
|
+
Geistdocs uses environment variables to configure Ask AI, optional Mixedbread retrieval for Ask AI and site search, optional Vertex-backed proxy mode, eve agent session cookie signing, and production URL behavior.
|
|
18
18
|
|
|
19
19
|
Review this Geistdocs project and help me configure the required environment variables. Check whether `AI_GATEWAY_API_KEY`, `MXBAI_API_KEY`, `MXBAI_STORE_ID`, `GEISTDOCS_CHAT_PROXY_URL`, `GEISTDOCS_CHAT_PROXY_TOKEN`, `GEISTDOCS_CHAT_SECRET`, 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.
|
|
20
20
|
|
|
@@ -28,13 +28,13 @@ Leave `GEISTDOCS_CHAT_PROXY_URL` unset to use AI Gateway mode.
|
|
|
28
28
|
|
|
29
29
|
## `MXBAI_API_KEY`
|
|
30
30
|
|
|
31
|
-
The server-only API key for Mixedbread retrieval. The Mixedbread Vercel Marketplace integration injects this value when you provision a Store and connect it to the consumer site's Vercel project.
|
|
31
|
+
The server-only API key for Mixedbread retrieval, used by Ask AI and site search. The Mixedbread Vercel Marketplace integration injects this value when you provision a Store and connect it to the consumer site's Vercel project.
|
|
32
32
|
|
|
33
33
|
## `MXBAI_STORE_ID`
|
|
34
34
|
|
|
35
|
-
The Mixedbread Store used by one consumer site.
|
|
35
|
+
The Mixedbread Store used by one consumer site. Configure a unique `siteId`, then set `ai.retrieval`, `search.provider`, or both to `"mixedbread"` before using this value. Ask AI and site search share this Store and `MXBAI_API_KEY`. When either value or `siteId` is missing at runtime, each surface that uses Mixedbread answers from local search instead.
|
|
36
36
|
|
|
37
|
-
Provision the Store by running `vercel integration add mixedbread` from the root of the consumer site's repository, where Vercel CLI is linked to that site's project. Do not run the provisioning command from the Geistdocs package repository. Read [Improve Ask AI
|
|
37
|
+
Provision the Store by running `vercel integration add mixedbread` from the root of the consumer site's repository, where Vercel CLI is linked to that site's project. Do not run the provisioning command from the Geistdocs package repository. Read [Improve Ask AI and site search with Mixedbread](/docs/mixedbread-retrieval) for the complete setup.
|
|
38
38
|
|
|
39
39
|
## `GEISTDOCS_CHAT_PROXY_URL`
|
|
40
40
|
|
package/docs/pages/index.md
CHANGED
|
@@ -78,7 +78,7 @@ Advanced projects can use package APIs for versioned docs, multiple content sour
|
|
|
78
78
|
- MDX documentation with custom components
|
|
79
79
|
- Local content in `content/docs`
|
|
80
80
|
- Search and Ask AI
|
|
81
|
-
- Optional Mixedbread semantic retrieval for Ask AI
|
|
81
|
+
- Optional Mixedbread semantic retrieval for Ask AI and site search
|
|
82
82
|
- Page actions, including feedback, copy page, open in chat, and edit on GitHub
|
|
83
83
|
- Agent-readiness metadata with `/agents.md` and `/.well-known/mcp.json`
|
|
84
84
|
- Raw Markdown routes for AI tools
|
package/docs/pages/llms-txt.md
CHANGED
|
@@ -82,7 +82,7 @@ export const { GET } = createLlmsRoute({
|
|
|
82
82
|
});
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
-
`filterPage` receives the page plus its language and source. Use the same synchronous filter function for every public aggregate route so `/llms.txt`, `sitemap.md`,
|
|
85
|
+
`filterPage` receives the page plus its language and source. Use the same synchronous filter function for every public aggregate route so `/llms.txt`, `sitemap.md`, site search, Mixedbread search export, and Ask AI expose the same cacheable page set. Pass that function as `canViewPage` to `createDocsMarkdownRoute`. Request-specific HTML access belongs in `createDocsPage({ canViewPage })`; do not personalize public indexes.
|
|
86
86
|
|
|
87
87
|
## The llms.txt standard
|
|
88
88
|
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: Improve Ask AI
|
|
3
|
-
description: Configure Mixedbread retrieval for
|
|
2
|
+
title: Improve Ask AI and site search with Mixedbread
|
|
3
|
+
description: Configure Mixedbread semantic retrieval for Geistdocs Ask AI, site search, or both, and sync documentation to a site-specific Store
|
|
4
4
|
type: guide
|
|
5
|
-
summary: Provision a Mixedbread Store for one Geistdocs consumer site,
|
|
5
|
+
summary: Provision a Mixedbread Store for one Geistdocs consumer site, turn on semantic retrieval for Ask AI with ai.retrieval and for site search with search.provider, and sync documentation during production builds.
|
|
6
6
|
url: /docs/mixedbread-retrieval
|
|
7
7
|
source: apps/template/content/docs/mixedbread-retrieval.mdx
|
|
8
8
|
prerequisites:
|
|
@@ -14,26 +14,35 @@ related:
|
|
|
14
14
|
- /docs/llms-txt
|
|
15
15
|
---
|
|
16
16
|
|
|
17
|
-
# Improve Ask AI
|
|
17
|
+
# Improve Ask AI and site search with Mixedbread
|
|
18
18
|
|
|
19
|
-
Mixedbread retrieval
|
|
19
|
+
Mixedbread retrieval matches documentation to a reader's words by meaning instead of by keyword. A Geistdocs site can use its Mixedbread Store for Ask AI, for site search, or for both, and each surface has its own setting.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Both settings default to local Orama search. A site that sets neither behaves exactly as before, and a site that already uses Mixedbread for Ask AI keeps the same Ask AI behavior.
|
|
22
22
|
|
|
23
|
-
Help me enable Mixedbread retrieval for this Geistdocs consumer site. Confirm that I am in this site's own repository and linked to the correct Vercel project before provisioning a Store. Then verify `siteId`, `ai.retrieval`, the search export route, the build script, and the `MXBAI` environment variables.
|
|
23
|
+
Help me enable Mixedbread retrieval for this Geistdocs consumer site. Confirm that I am in this site's own repository and linked to the correct Vercel project before provisioning a Store. Then verify `siteId`, `ai.retrieval`, `search.provider`, the `search` config forwarded by `lib/geistdocs/config.tsx`, the search export route, the build script, and the `MXBAI` environment variables.
|
|
24
24
|
|
|
25
25
|
## How Mixedbread retrieval works
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
Two independent settings decide which surfaces read the Store:
|
|
28
|
+
|
|
29
|
+
| Setting | Surfaces | Default |
|
|
30
|
+
| --- | --- | --- |
|
|
31
|
+
| `ai.retrieval: "mixedbread"` | The documentation retrieval Ask AI runs before it sends a question to the AI model | `"local"` |
|
|
32
|
+
| `search.provider: "mixedbread"` | The search dialog, `GET /api/search`, and the MCP `search_docs` tool, which calls the same route | `"local"` |
|
|
33
|
+
|
|
34
|
+
A site can set either, both, or neither. One Store and one sync serve both surfaces.
|
|
35
|
+
|
|
36
|
+
For Ask AI, the default local retriever matches keywords with Orama. Mixedbread adds semantic matching and returns the relevant content chunk instead of the start of a matching page. The AI model stays the same.
|
|
37
|
+
|
|
38
|
+
For site search, Mixedbread ranks pages and sections, and Geistdocs renders each result from the running deployment. The response shape stays the same, so the search dialog needs no change.
|
|
28
39
|
|
|
29
40
|
The production build performs an incremental sync:
|
|
30
41
|
|
|
31
42
|
1. Next.js statically generates `/api/search/export` from the site's configured content sources.
|
|
32
43
|
2. `geistdocs search sync` uploads new or changed Markdown documents to the site's Mixedbread Store.
|
|
33
|
-
3. Ask AI
|
|
34
|
-
4. Geistdocs
|
|
35
|
-
|
|
36
|
-
Pages with `internal: true` or `excludeFrom: [chat]` are omitted from the export and removed from the Store on the next successful sync.
|
|
44
|
+
3. Ask AI, site search, or both query the Store by `siteId` and locale.
|
|
45
|
+
4. Geistdocs answers from the local Orama index if Mixedbread is unavailable or its credentials are missing at runtime.
|
|
37
46
|
|
|
38
47
|
## Prerequisites
|
|
39
48
|
|
|
@@ -41,7 +50,7 @@ Before enabling Mixedbread retrieval, confirm that:
|
|
|
41
50
|
|
|
42
51
|
- The Mixedbread Marketplace integration is installed on your Vercel team.
|
|
43
52
|
- The consumer site has its own Vercel project.
|
|
44
|
-
- The consumer repository uses a Geistdocs release that includes `geistdocs search sync` and `createSearchExportRoute`.
|
|
53
|
+
- The consumer repository uses a Geistdocs release that includes `geistdocs search sync` and `createSearchExportRoute`. Site search needs a release that includes `search.provider`.
|
|
45
54
|
- `source.config.ts` enables `includeProcessedMarkdown`, as generated Geistdocs projects do by default.
|
|
46
55
|
- `next.config.ts` enables `cacheComponents`, as generated Geistdocs projects do by default. Next.js must statically prerender `/api/search/export` before the sync command runs.
|
|
47
56
|
|
|
@@ -76,7 +85,13 @@ vercel integration list --integration mixedbread
|
|
|
76
85
|
|
|
77
86
|
## Configure the consumer site
|
|
78
87
|
|
|
79
|
-
Set a unique `siteId`
|
|
88
|
+
Set a unique `siteId` in the consumer repository's root `geistdocs.tsx` file, then turn on Mixedbread for Ask AI, site search, or both. Both surfaces need `siteId`, and both read the same `MXBAI_API_KEY` and `MXBAI_STORE_ID` variables.
|
|
89
|
+
|
|
90
|
+
Keep `MXBAI_API_KEY` and `MXBAI_STORE_ID` out of `geistdocs.tsx` and every other config value, because that config is available to client components.
|
|
91
|
+
|
|
92
|
+
### Use Mixedbread for Ask AI
|
|
93
|
+
|
|
94
|
+
Set `ai.retrieval` in `geistdocs.tsx`:
|
|
80
95
|
|
|
81
96
|
```tsx title="geistdocs.tsx"
|
|
82
97
|
import type {
|
|
@@ -90,7 +105,64 @@ export const ai = {
|
|
|
90
105
|
} satisfies GeistdocsAIConfig;
|
|
91
106
|
```
|
|
92
107
|
|
|
93
|
-
The generated `lib/geistdocs/config.tsx` spreads `ai` into the package config.
|
|
108
|
+
The generated `lib/geistdocs/config.tsx` spreads `ai` into the package config.
|
|
109
|
+
|
|
110
|
+
### Use Mixedbread for site search
|
|
111
|
+
|
|
112
|
+
Site search takes two edits. First, set `search.provider` in `geistdocs.tsx`:
|
|
113
|
+
|
|
114
|
+
```tsx title="geistdocs.tsx"
|
|
115
|
+
import type {
|
|
116
|
+
GeistdocsSearchConfig,
|
|
117
|
+
} from "@vercel/geistdocs/config";
|
|
118
|
+
|
|
119
|
+
export const siteId = "my-product-docs";
|
|
120
|
+
|
|
121
|
+
export const search = {
|
|
122
|
+
provider: "mixedbread",
|
|
123
|
+
} satisfies GeistdocsSearchConfig;
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Second, make sure `lib/geistdocs/config.tsx` imports `search` and passes it to `defineConfig`:
|
|
127
|
+
|
|
128
|
+
```tsx title="lib/geistdocs/config.tsx"
|
|
129
|
+
import { defineConfig } from "@vercel/geistdocs/config";
|
|
130
|
+
import {
|
|
131
|
+
// ...your other exports
|
|
132
|
+
search,
|
|
133
|
+
siteId,
|
|
134
|
+
} from "@/geistdocs";
|
|
135
|
+
|
|
136
|
+
export const config = defineConfig({
|
|
137
|
+
// ...
|
|
138
|
+
search,
|
|
139
|
+
siteId,
|
|
140
|
+
});
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
New projects generated from the template already export `search` as `{}` and forward it, so they only change the `provider` value. A site created before this release adds the `search` export and the forward once. Without the forward, the setting never reaches the search route, and search stays local with no error.
|
|
144
|
+
|
|
145
|
+
The search route file doesn't change. `createSearchRoute({ config, sources })` reads `search.provider` from `config`, and `search.enabled` keeps its existing meaning.
|
|
146
|
+
|
|
147
|
+
### Override the connection on the server
|
|
148
|
+
|
|
149
|
+
To pass credentials another way, or to use a non-default Mixedbread API origin, set the server-only `mixedbread` option on the search route. It has the same shape as the `mixedbread` option on `createChatRoute`:
|
|
150
|
+
|
|
151
|
+
```ts title="app/api/search/route.ts"
|
|
152
|
+
import { createSearchRoute } from "@vercel/geistdocs/routes/search";
|
|
153
|
+
import { config } from "@/lib/geistdocs/config";
|
|
154
|
+
import { geistdocsSource } from "@/lib/geistdocs/source";
|
|
155
|
+
|
|
156
|
+
export const GET = createSearchRoute({
|
|
157
|
+
config,
|
|
158
|
+
sources: [geistdocsSource],
|
|
159
|
+
mixedbread: {
|
|
160
|
+
apiBaseUrl: "https://mixedbread.example.com/v1",
|
|
161
|
+
},
|
|
162
|
+
});
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
The option also accepts `apiKey`, `storeId`, and `requestTimeoutMs`, which defaults to 1,500 ms for site search. `MXBAI_API_KEY` and `MXBAI_STORE_ID` fill any credential you omit. The runtime does not read `MXBAI_BASE_URL`. Only the `geistdocs search sync` command reads it, so set `apiBaseUrl` on the route for runtime requests.
|
|
94
166
|
|
|
95
167
|
## Add the export route to an existing site
|
|
96
168
|
|
|
@@ -109,6 +181,38 @@ export const { GET } = createSearchExportRoute({
|
|
|
109
181
|
|
|
110
182
|
Pass every configured source in `sources` when the site has multiple sections or documentation versions.
|
|
111
183
|
|
|
184
|
+
## Control which pages reach the Store
|
|
185
|
+
|
|
186
|
+
The export holds the pages of every surface that reads the Store:
|
|
187
|
+
|
|
188
|
+
| Configuration | Pages in the export |
|
|
189
|
+
| --- | --- |
|
|
190
|
+
| Only `ai.retrieval: "mixedbread"` | Chat-visible pages, as before |
|
|
191
|
+
| Only `search.provider: "mixedbread"` | Search-visible pages |
|
|
192
|
+
| Both | Pages visible to chat, search, or both |
|
|
193
|
+
|
|
194
|
+
Pages with `internal: true` are never exported. A page that leaves the export is removed from the Store on the next successful sync.
|
|
195
|
+
|
|
196
|
+
When site search uses Mixedbread, a page with `excludeFrom: [chat]` that search can still show is uploaded to the Mixedbread Store. Ask AI still never retrieves it, because Ask AI checks every Store hit against chat visibility.
|
|
197
|
+
|
|
198
|
+
Each surface checks every Store hit against the running deployment before it uses the hit. Site search never shows a page with `excludeFrom: [search]`, an `internal: true` page, a page that the search route's `filterPage` rejects, or a page that no longer exists, whatever the Store holds. Ask AI applies the same check for chat.
|
|
199
|
+
|
|
200
|
+
To keep a page out of the Store entirely, reject it with `filterPage` on the export route:
|
|
201
|
+
|
|
202
|
+
```ts title="app/api/search/export/route.ts"
|
|
203
|
+
import { createSearchExportRoute } from "@vercel/geistdocs/routes/search-export";
|
|
204
|
+
import { config } from "@/lib/geistdocs/config";
|
|
205
|
+
import { geistdocsSource } from "@/lib/geistdocs/source";
|
|
206
|
+
|
|
207
|
+
export const { GET } = createSearchExportRoute({
|
|
208
|
+
config,
|
|
209
|
+
sources: [geistdocsSource],
|
|
210
|
+
filterPage: (page) => !page.url.includes("/internal"),
|
|
211
|
+
});
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Pass the same `filterPage` to the export, chat, and search routes. The search route can only drop more hits at request time, and a page that the export filter rejects is not in the Store.
|
|
215
|
+
|
|
112
216
|
## Sync after each production build
|
|
113
217
|
|
|
114
218
|
New Geistdocs projects run the sync from their build script. For an existing site, update `package.json`:
|
|
@@ -121,7 +225,9 @@ New Geistdocs projects run the sync from their build script. For an existing sit
|
|
|
121
225
|
}
|
|
122
226
|
```
|
|
123
227
|
|
|
124
|
-
Deploy the site to production. The first production build uploads every
|
|
228
|
+
Deploy the site to production. The first production build uploads every exported page. Later builds upload changed pages and remove stale pages while leaving unrelated Store files untouched.
|
|
229
|
+
|
|
230
|
+
The sync runs when Ask AI, site search, or both use Mixedbread. When neither does, it prints `Geistdocs search sync skipped: neither Ask AI nor site search uses Mixedbread.`
|
|
125
231
|
|
|
126
232
|
Local and preview builds skip the remote sync. To test a sync outside a production Vercel build, build the site and run the sync with the linked project's production environment variables:
|
|
127
233
|
|
|
@@ -131,14 +237,64 @@ vercel env run --environment production -- \
|
|
|
131
237
|
pnpm exec geistdocs search sync --allow-non-production
|
|
132
238
|
```
|
|
133
239
|
|
|
134
|
-
The sync command fails when
|
|
240
|
+
The sync command fails when Ask AI or site search uses Mixedbread for a production build but the Store environment variables are missing. The error prints the provisioning command and reminds you to run it from the correct consumer repository.
|
|
241
|
+
|
|
242
|
+
An existing Ask AI site uploads nothing new when it upgrades Geistdocs, because Store metadata and content hashes are unchanged. Turning on `search.provider` adds the search-visible pages that chat excludes.
|
|
243
|
+
|
|
244
|
+
## Preview and local deployments
|
|
245
|
+
|
|
246
|
+
The Store holds the content of the last production sync. Preview and local deployments that have the `MXBAI_*` variables query the production Store, and Geistdocs still renders and checks every result against the deployment that serves the request.
|
|
247
|
+
|
|
248
|
+
A page that exists only in a preview deployment is not in the Store. That page appears in search results only when local search answers.
|
|
249
|
+
|
|
250
|
+
The provisioning command connects the Store to the production environment. A preview deployment without the `MXBAI_*` variables serves local search and local Ask AI retrieval.
|
|
251
|
+
|
|
252
|
+
## What readers see in site search
|
|
253
|
+
|
|
254
|
+
Mixedbread decides which pages and sections match and in what order. Every string in a result, including the title, breadcrumbs, heading, anchor, excerpt, and URL, comes from the page in the running deployment. Geistdocs never shows text stored in Mixedbread.
|
|
255
|
+
|
|
256
|
+
Each query returns up to 8 pages, and each page shows up to 3 sections. URLs stay app-local, as they are with local search. The generated OpenAPI document describes the search operation as semantic search when `search.provider` is `"mixedbread"`.
|
|
257
|
+
|
|
258
|
+
## When local search answers instead
|
|
259
|
+
|
|
260
|
+
Site search never fails because of Mixedbread. The search route answers from the local index with status 200 when:
|
|
261
|
+
|
|
262
|
+
- `MXBAI_API_KEY`, `MXBAI_STORE_ID`, or `siteId` is missing. The server logs one warning per route instance, such as `[Geistdocs search] search.provider is "mixedbread" but MXBAI_STORE_ID is missing. Serving local search.`
|
|
263
|
+
- The Mixedbread request fails or exceeds its timeout, which is 1,500 ms by default, with no retries. The server logs `[Geistdocs search] Mixedbread search failed. Serving local search.` with the error.
|
|
264
|
+
- Mixedbread returns nothing that the deployment can show, for example before the first production sync.
|
|
265
|
+
|
|
266
|
+
The local route always answers these requests without calling Mixedbread:
|
|
267
|
+
|
|
268
|
+
- A request with an empty query.
|
|
269
|
+
- A request with a `tag` parameter. The built-in local index still returns no results for a tagged request, as before.
|
|
270
|
+
- A request for a locale the site does not configure.
|
|
135
271
|
|
|
136
272
|
## Verify retrieval
|
|
137
273
|
|
|
138
|
-
Open the Mixedbread dashboard through Vercel and confirm that the Store contains one file per
|
|
274
|
+
Open the Mixedbread dashboard through Vercel and confirm that the Store contains one file per exported documentation page:
|
|
139
275
|
|
|
140
276
|
```bash title="Terminal"
|
|
141
277
|
vercel integration open mixedbread
|
|
142
278
|
```
|
|
143
279
|
|
|
280
|
+
### Verify Ask AI
|
|
281
|
+
|
|
144
282
|
Ask a question that uses different words from the page title. Ask AI should cite the relevant page and answer from the matching section. If Mixedbread returns an error or exceeds the request timeout, Geistdocs logs a warning and retries the question with local Orama retrieval.
|
|
283
|
+
|
|
284
|
+
### Verify site search
|
|
285
|
+
|
|
286
|
+
Every search response from a site with `search.provider: "mixedbread"` carries the `x-geistdocs-search-provider` header. Request a query and read the header:
|
|
287
|
+
|
|
288
|
+
```bash title="Terminal"
|
|
289
|
+
curl -si 'https://docs.example.com/api/search?query=deploy%20a%20site&locale=en'
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
| Header value | Meaning |
|
|
293
|
+
| --- | --- |
|
|
294
|
+
| `mixedbread` | Mixedbread ranked the results. |
|
|
295
|
+
| `local` | The site opted in, but local search answered this request. Check the server logs for a warning. |
|
|
296
|
+
| No header | The setting did not reach the search route. Check that `geistdocs.tsx` sets `search.provider` and that `lib/geistdocs/config.tsx` forwards `search`. |
|
|
297
|
+
|
|
298
|
+
## Request cost
|
|
299
|
+
|
|
300
|
+
The search dialog sends one request per debounced query. Each request that reaches Mixedbread is one Mixedbread search request. Geistdocs does not cache search results.
|
package/docs/pages/provider.md
CHANGED
|
@@ -25,6 +25,9 @@ The provider handles these behaviors:
|
|
|
25
25
|
2. **Analytics**: Integrates Vercel Analytics and Speed Insights when the local adapter includes them.
|
|
26
26
|
3. **Search**: Configures the search dialog and connects it to your search API.
|
|
27
27
|
4. **Ask AI**: Provides the client state used by the chat sidebar and page actions.
|
|
28
|
+
5. **Theme shortcut**: Press `T` with no modifiers while the page has focus to switch between light and dark themes. The shortcut is disabled when a theme is forced.
|
|
29
|
+
|
|
30
|
+
The shortcut is part of the package provider, so generated consumer projects get it by default. It does not run while an input, button, link, or other element has focus.
|
|
28
31
|
|
|
29
32
|
## Usage
|
|
30
33
|
|
package/docs/sitemap.md
CHANGED
|
@@ -5,7 +5,7 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
|
|
|
5
5
|
|
|
6
6
|
- [Overview](pages/index.md) | URL: /docs | Type: overview | Summary: Geistdocs is a packaged documentation system for creating Next.js and Fumadocs sites with shared runtime features.
|
|
7
7
|
- [Getting Started](pages/getting-started.md) | URL: /docs/getting-started | Type: guide | Summary: Create a Geistdocs project, run it locally, and edit your first documentation page.
|
|
8
|
-
- [Environment Variables](pages/env.md) | URL: /docs/env | Type: reference | Summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, eve agent session cookies, and production URL configuration.
|
|
8
|
+
- [Environment Variables](pages/env.md) | URL: /docs/env | Type: reference | Summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval for Ask AI and site search, proxy mode, eve agent session cookies, and production URL configuration.
|
|
9
9
|
- [Deploy to Vercel](pages/deployment.md) | URL: /docs/deployment | Type: guide | Summary: Deploy a Geistdocs site to Vercel with the required project settings and environment variables.
|
|
10
10
|
- [Migrate to Geistdocs](pages/migration.md) | URL: /docs/migration | Type: guide | Summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
|
|
11
11
|
- [Choose a Geistdocs package](pages/packages.md) | URL: /docs/packages | Type: guide | Summary: Use the public package by default and the private package only where restricted Vercel npm dependencies are already available.
|
|
@@ -33,7 +33,7 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
|
|
|
33
33
|
- [Edit on GitHub](pages/edit-on-github.md) | URL: /docs/edit-on-github | Type: integration | Summary: A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
|
|
34
34
|
- [Feedback](pages/feedback.md) | URL: /docs/feedback | Type: integration | Summary: An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
|
|
35
35
|
- [Image](pages/components/image.md) | URL: /docs/components/image | Type: reference | Summary: Use the Geistdocs Image wrapper for documentation-aware Next.js images.
|
|
36
|
-
- [Improve Ask AI
|
|
36
|
+
- [Improve Ask AI and site search with Mixedbread](pages/mixedbread-retrieval.md) | URL: /docs/mixedbread-retrieval | Type: guide | Summary: Provision a Mixedbread Store for one Geistdocs consumer site, turn on semantic retrieval for Ask AI with ai.retrieval and for site search with search.provider, and sync documentation during production builds.
|
|
37
37
|
- [Input](pages/components/input.md) | URL: /docs/components/input | Type: reference | Summary: Use Input for text entry in custom documentation and application interfaces.
|
|
38
38
|
- [Internationalization](pages/internationalization.md) | URL: /docs/internationalization | Type: guide | Summary: Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
|
|
39
39
|
- [llms.txt](pages/llms-txt.md) | URL: /docs/llms-txt | Type: conceptual | Summary: A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vercel/geistdocs",
|
|
3
3
|
"description": "Runtime and CLI for Geistdocs projects.",
|
|
4
|
-
"version": "2.14.
|
|
4
|
+
"version": "2.14.7-canary.6ce58a6",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -301,6 +301,10 @@
|
|
|
301
301
|
"./theme.css": "./theme.css",
|
|
302
302
|
"./package.json": "./package.json"
|
|
303
303
|
},
|
|
304
|
+
"scripts": {
|
|
305
|
+
"build": "rm -rf dist docs template && node ./scripts/bundle-template.mjs && node ./scripts/bundle-docs.mjs && tsc -p tsconfig.runtime.json && tsup --config tsup.config.cli.ts",
|
|
306
|
+
"dev": "tsc -p tsconfig.runtime.json --watch --preserveWatchOutput"
|
|
307
|
+
},
|
|
304
308
|
"dependencies": {
|
|
305
309
|
"@ai-sdk/react": "^3.0.134",
|
|
306
310
|
"@clack/prompts": "^0.11.0",
|
|
@@ -364,9 +368,5 @@
|
|
|
364
368
|
"react-dom": "^19.2.3",
|
|
365
369
|
"tsup": "^8.5.1",
|
|
366
370
|
"typescript": "^5.9.3"
|
|
367
|
-
},
|
|
368
|
-
"scripts": {
|
|
369
|
-
"build": "rm -rf dist docs template && node ./scripts/bundle-template.mjs && node ./scripts/bundle-docs.mjs && tsc -p tsconfig.runtime.json && tsup --config tsup.config.cli.ts",
|
|
370
|
-
"dev": "tsc -p tsconfig.runtime.json --watch --preserveWatchOutput"
|
|
371
371
|
}
|
|
372
|
-
}
|
|
372
|
+
}
|
package/template/.env.example
CHANGED
package/template/AGENTS.md
CHANGED
|
@@ -25,7 +25,7 @@ Use these instructions when an AI coding agent edits this project.
|
|
|
25
25
|
|
|
26
26
|
| Task | Edit |
|
|
27
27
|
| --- | --- |
|
|
28
|
-
| Configure site title, logo, nav, GitHub links, AI prompt, retrieval, suggestions, translations, `basePath`, or `siteId` | `geistdocs.tsx` |
|
|
28
|
+
| Configure site title, logo, nav, GitHub links, AI prompt, retrieval, search provider, suggestions, translations, `basePath`, or `siteId` | `geistdocs.tsx` |
|
|
29
29
|
| Add or update documentation pages | `content/docs/**/*.mdx` |
|
|
30
30
|
| Control sidebar order, groups, and folder labels | `content/docs/meta.json` |
|
|
31
31
|
| Give a page a shorter navigation label | Set `navTitle` in the page's frontmatter |
|
|
@@ -67,14 +67,18 @@ Use these instructions when an AI coding agent edits this project.
|
|
|
67
67
|
- Use `createDocsPage({ canViewPage })` and its returned `getPageTree(params)` for request-specific page access. Use one synchronous public filter as `canViewPage` for per-page Markdown and as `filterPage` for llms.txt, sitemap, search, search export, and chat routes.
|
|
68
68
|
- Include `"/"` explicitly in the static proxy matcher when a Next.js base-path application serves documentation at its app root.
|
|
69
69
|
|
|
70
|
-
## Ask AI and Vertex proxy guidelines
|
|
70
|
+
## Ask AI, Mixedbread, and Vertex proxy guidelines
|
|
71
71
|
|
|
72
72
|
- Leave `GEISTDOCS_CHAT_PROXY_URL` unset and `ai.eveAgent` unconfigured to use the default AI Gateway path. In that mode, `app/api/chat/route.ts` calls `createChatRoute` without a `proxy` option and uses the local docs search tool during the AI SDK `streamText` loop.
|
|
73
|
-
- Set `ai.retrieval: "mixedbread"` with a unique `siteId` to use Mixedbread semantic retrieval for Ask AI.
|
|
73
|
+
- Set `ai.retrieval: "mixedbread"` with a unique `siteId` to use Mixedbread semantic retrieval for Ask AI. This setting does not change site search.
|
|
74
|
+
- Set `search.provider: "mixedbread"` in the `search` export of `geistdocs.tsx`, with a unique `siteId`, to rank the search dialog, `/api/search`, and the MCP `search_docs` tool with the same Store. `lib/geistdocs/config.tsx` must import `search` from `@/geistdocs` and pass it to `defineConfig`. Add that forward if it is missing, because without it search stays local with no error. Leave `app/api/search/route.ts` unchanged, because it reads the setting from `config`. Both settings default to local Orama search and are independent.
|
|
75
|
+
- Check site search with the `x-geistdocs-search-provider` header on an `/api/search?query=...` response. `mixedbread` means the Store answered. `local` means a fallback, caused by missing `MXBAI_*` variables or `siteId` (the server logs a warning), a failed request or one over the 1,500 ms timeout, or no hits this deployment can show. No header means the setting never reached the route. Empty queries, `tag` requests, and unconfigured locales always use local search.
|
|
74
76
|
- Provision a Mixedbread Store from the root of this consumer site's repository, where Vercel CLI is linked to this site's Vercel project. Never run `vercel integration add mixedbread` from the Geistdocs package repository or another consumer repository.
|
|
75
|
-
- Keep `MXBAI_API_KEY` and `MXBAI_STORE_ID` in environment variables. Never put them in `geistdocs.tsx`, because config is available to client components.
|
|
76
|
-
- Keep `app/api/search/export/route.ts` and the `next build && geistdocs search sync` build script when
|
|
77
|
-
-
|
|
77
|
+
- Keep `MXBAI_API_KEY` and `MXBAI_STORE_ID` in environment variables. Never put them in `geistdocs.tsx`, because config is available to client components. Pass server-only overrides as the `mixedbread` option on `createSearchRoute` or `createChatRoute`. The runtime does not read `MXBAI_BASE_URL` (only `geistdocs search sync` does), so set `mixedbread.apiBaseUrl` for a non-default API origin.
|
|
78
|
+
- Keep `app/api/search/export/route.ts` and the `next build && geistdocs search sync` build script when Ask AI or site search uses Mixedbread. Production builds incrementally sync the pages of every surface that reads the Store. That is chat-visible pages for `ai.retrieval`, search-visible pages for `search.provider`, and the union for both. Local and preview builds skip remote sync unless `--allow-non-production` is passed, and they query the production Store when they have credentials.
|
|
79
|
+
- With `search.provider: "mixedbread"`, a page with `excludeFrom: [chat]` that search can show is uploaded to the Store, and Ask AI still never retrieves it. To keep a page out of the Store, reject it with `filterPage` on `createSearchExportRoute`, and pass the same filter to the export, chat, and search routes.
|
|
80
|
+
- Mixedbread failures fall back to local Orama retrieval for each surface. Keep the local source definitions and the `excludeFrom: [chat]` and `excludeFrom: [search]` visibility behavior intact.
|
|
81
|
+
- Each debounced search dialog query that reaches Mixedbread is one Mixedbread search request. Geistdocs does not cache search results.
|
|
78
82
|
- Set `ai.eveAgent: { url }` in `geistdocs.tsx` to answer Ask AI with a hosted eve framework agent instead. The URL flows through the config object; the route file needs no changes. Set `prewarm: true` for eve 0.59+ responders when the site should prepare an empty durable session as the chat client loads. Requests authenticate with a per-request Vercel OIDC bearer token by default; pass server-only headers through the `eveAgent` option on `createChatRoute` for custom auth. Never put auth material in `geistdocs.tsx`. Configuring both `proxy` and an eve agent throws at route creation.
|
|
79
83
|
- Set the server-only `GEISTDOCS_CHAT_SECRET` (at least 32 bytes, generate with `openssl rand -base64 32`) for eve agent mode. It signs the httpOnly `geistdocs_eve_session` cookie that binds a browser to its eve session (the cookie is `SameSite=Strict`, so keep the chat route on the same site as the docs pages); without it every turn starts a new eve session and prewarm requests are refused. Never prefix it with `NEXT_PUBLIC_` or put it in `geistdocs.tsx`.
|
|
80
84
|
- `createChatRoute` caps request size (1,000,000-byte body, 200 messages, 200,000-character `pageContext.content` by default; override with the `limits` option). It does not rate limit, so wrap `POST` with the site's own rate limiting.
|
|
@@ -123,7 +127,7 @@ Use these instructions when an AI coding agent edits this project.
|
|
|
123
127
|
- Run `pnpm build` after changing routes, config, source setup, MDX components, or package versions.
|
|
124
128
|
- Run `pnpm dev` and open the changed pages when visual layout, navigation, or MDX rendering changes.
|
|
125
129
|
- Check both `/docs` and AI-readable routes such as `/agents.md`, `/.well-known/mcp.json`, `/llms.txt`, or a page-level `.md` URL when changing content routing or proxy behavior.
|
|
126
|
-
- Confirm `/api/search/export` is statically generated after changing
|
|
130
|
+
- Confirm `/api/search/export` is statically generated after changing `ai.retrieval`, `search.provider`, or source configuration.
|
|
127
131
|
- Confirm no secrets were added to source files. Use `.env.local` for local values and keep it out of Git.
|
|
128
132
|
|
|
129
133
|
<!-- BEGIN:nextjs-agent-rules -->
|
|
@@ -50,9 +50,25 @@ Once open, users can:
|
|
|
50
50
|
- Ask questions about any part of your documentation
|
|
51
51
|
- View the documentation pages used as sources for each answer
|
|
52
52
|
- Copy an answer as Markdown
|
|
53
|
+
- Share a conversation with a public link when the site configures chat sharing
|
|
53
54
|
- Expand the desktop panel to fill the viewport
|
|
54
55
|
- Get step-by-step guidance on complex topics
|
|
55
56
|
|
|
57
|
+
### Share a conversation
|
|
58
|
+
|
|
59
|
+
To show **Share chat** in the chat header, set `ai.share` to an app-local POST endpoint and the public route that displays shared conversations:
|
|
60
|
+
|
|
61
|
+
```tsx title="geistdocs.tsx"
|
|
62
|
+
export const ai = {
|
|
63
|
+
share: {
|
|
64
|
+
endpoint: "/api/ai-chat/share",
|
|
65
|
+
path: "/ai-chat",
|
|
66
|
+
},
|
|
67
|
+
};
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Geistdocs sends the endpoint a JSON body with `messages`, `hostPath`, and an optional `summary` containing the first user message. The endpoint must persist the conversation and return `{ "shareId": "..." }`. Geistdocs copies a link to `<path>/<shareId>`; your app must serve that public route and load the saved conversation. The endpoint and path are app-local, and Geistdocs adds `basePath` when needed. Chat sharing is disabled when `ai.share` is unset.
|
|
71
|
+
|
|
56
72
|
## Control Ask AI from your own components
|
|
57
73
|
|
|
58
74
|
`useGeistdocsChat` from `@vercel/geistdocs/controls` opens, closes, and sends messages to the Ask AI chat from your own client components. Call it from any component rendered inside `GeistdocsProvider`, such as a custom header, a callout, or an MDX component.
|
|
@@ -702,7 +718,7 @@ By default, the AI assistant includes a built-in `search_docs` tool that:
|
|
|
702
718
|
|
|
703
719
|
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. With `contextInjection: "page-only"`, Geistdocs skips this retrieval.
|
|
704
720
|
|
|
705
|
-
Set `ai.retrieval` to `"mixedbread"` to replace local keyword retrieval with semantic retrieval for default, proxy, and hosted eve modes. Mixedbread returns the matching content chunk, while the AI model
|
|
721
|
+
Set `ai.retrieval` to `"mixedbread"` to replace local keyword retrieval with semantic retrieval for default, proxy, and hosted eve modes. Mixedbread returns the matching content chunk, while the AI model stays the same. Geistdocs falls back to local Orama retrieval when Mixedbread is unavailable. `ai.retrieval` does not change the search dialog. To serve site search from the same Store, set `search.provider` to `"mixedbread"` as well. Read [Improve Ask AI and site search with Mixedbread](/docs/mixedbread-retrieval) to provision a Store and configure production sync.
|
|
706
722
|
|
|
707
723
|
### Persistent Chat History
|
|
708
724
|
|