@vercel/geistdocs 2.14.6 → 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.
Files changed (79) hide show
  1. package/dist/cli/index.js +5 -5
  2. package/dist/config.d.ts +23 -3
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/controls.d.ts +3 -40
  5. package/dist/controls.d.ts.map +1 -1
  6. package/dist/controls.js +5 -96
  7. package/dist/internal/chat-retrieval.d.ts +10 -9
  8. package/dist/internal/chat-retrieval.d.ts.map +1 -1
  9. package/dist/internal/chat-retrieval.js +32 -68
  10. package/dist/internal/controls-client.d.ts +40 -0
  11. package/dist/internal/controls-client.d.ts.map +1 -0
  12. package/dist/internal/controls-client.js +87 -0
  13. package/dist/internal/language-selector.d.ts +2 -0
  14. package/dist/internal/language-selector.d.ts.map +1 -0
  15. package/dist/internal/language-selector.js +12 -0
  16. package/dist/internal/mixedbread-store.d.ts +53 -0
  17. package/dist/internal/mixedbread-store.d.ts.map +1 -0
  18. package/dist/internal/mixedbread-store.js +129 -0
  19. package/dist/internal/navbar/mobile-menu.js +1 -1
  20. package/dist/internal/page-action-options.d.ts +37 -0
  21. package/dist/internal/page-action-options.d.ts.map +1 -0
  22. package/dist/internal/page-action-options.js +39 -0
  23. package/dist/internal/page-actions-client.d.ts +1 -31
  24. package/dist/internal/page-actions-client.d.ts.map +1 -1
  25. package/dist/internal/page-actions-client.js +5 -103
  26. package/dist/internal/page-actions-gate.d.ts +3 -0
  27. package/dist/internal/page-actions-gate.d.ts.map +1 -0
  28. package/dist/internal/page-actions-gate.js +15 -0
  29. package/dist/internal/provider-client.d.ts.map +1 -1
  30. package/dist/internal/provider-client.js +26 -1
  31. package/dist/internal/relative-docs-link.d.ts +7 -0
  32. package/dist/internal/relative-docs-link.d.ts.map +1 -0
  33. package/dist/internal/relative-docs-link.js +22 -0
  34. package/dist/internal/sidebar.d.ts.map +1 -1
  35. package/dist/internal/sidebar.js +1 -1
  36. package/dist/internal/toc-actions-client.d.ts +9 -0
  37. package/dist/internal/toc-actions-client.d.ts.map +1 -0
  38. package/dist/internal/toc-actions-client.js +78 -0
  39. package/dist/mdx.d.ts.map +1 -1
  40. package/dist/mdx.js +5 -2
  41. package/dist/navbar.js +1 -1
  42. package/dist/pages/changelog.js +1 -1
  43. package/dist/pages/docs.d.ts.map +1 -1
  44. package/dist/pages/docs.js +4 -3
  45. package/dist/routes/chat.d.ts +4 -4
  46. package/dist/routes/chat.d.ts.map +1 -1
  47. package/dist/routes/chat.js +19 -34
  48. package/dist/routes/openapi.d.ts.map +1 -1
  49. package/dist/routes/openapi.js +13 -5
  50. package/dist/routes/search-export.d.ts +1 -1
  51. package/dist/routes/search-export.d.ts.map +1 -1
  52. package/dist/routes/search-export.js +5 -2
  53. package/dist/routes/search.d.ts +10 -2
  54. package/dist/routes/search.d.ts.map +1 -1
  55. package/dist/routes/search.js +215 -55
  56. package/docs/agents.md +3 -3
  57. package/docs/llms.txt +214 -32
  58. package/docs/manifest.json +5 -5
  59. package/docs/pages/ask-ai.md +1 -1
  60. package/docs/pages/configuration.md +26 -3
  61. package/docs/pages/env.md +5 -5
  62. package/docs/pages/index.md +1 -1
  63. package/docs/pages/llms-txt.md +1 -1
  64. package/docs/pages/mixedbread-retrieval.md +174 -18
  65. package/docs/pages/provider.md +3 -0
  66. package/docs/sitemap.md +2 -2
  67. package/package.json +6 -6
  68. package/template/.env.example +1 -0
  69. package/template/AGENTS.md +11 -7
  70. package/template/content/docs/ask-ai.mdx +1 -1
  71. package/template/content/docs/configuration.mdx +26 -3
  72. package/template/content/docs/env.mdx +5 -5
  73. package/template/content/docs/index.mdx +1 -1
  74. package/template/content/docs/llms-txt.mdx +1 -1
  75. package/template/content/docs/mixedbread-retrieval.mdx +174 -18
  76. package/template/content/docs/provider.mdx +3 -0
  77. package/template/geistdocs.tsx +6 -1
  78. package/template/lib/geistdocs/config.tsx +2 -0
  79. package/template/package.json +1 -1
@@ -1,8 +1,8 @@
1
1
  ---
2
- title: Improve Ask AI answers with Mixedbread
3
- description: Configure Mixedbread retrieval for a Geistdocs Ask AI chat and sync documentation to a site-specific Store
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, enable semantic retrieval, and sync documentation during production builds.
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
  prerequisites:
7
7
  - /docs/ask-ai
8
8
  - /docs/env
@@ -12,26 +12,35 @@ related:
12
12
  - /docs/llms-txt
13
13
  ---
14
14
 
15
- Mixedbread retrieval gives Ask AI the documentation passages that best match a user's question. The AI model stays the same, while semantic retrieval improves the evidence included with each question.
15
+ 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.
16
16
 
17
- Geistdocs keeps the visible search dialog on its local Orama index. Mixedbread only changes the documentation retrieval used by Ask AI.
17
+ 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.
18
18
 
19
- <CopyPrompt text="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.">
20
- 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.
19
+ <CopyPrompt text="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.">
20
+ 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.
21
21
  </CopyPrompt>
22
22
 
23
23
  ## How Mixedbread retrieval works
24
24
 
25
- Ask AI searches documentation before sending a question to the configured AI model. 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.
25
+ Two independent settings decide which surfaces read the Store:
26
+
27
+ | Setting | Surfaces | Default |
28
+ | --- | --- | --- |
29
+ | `ai.retrieval: "mixedbread"` | The documentation retrieval Ask AI runs before it sends a question to the AI model | `"local"` |
30
+ | `search.provider: "mixedbread"` | The search dialog, `GET /api/search`, and the MCP `search_docs` tool, which calls the same route | `"local"` |
31
+
32
+ A site can set either, both, or neither. One Store and one sync serve both surfaces.
33
+
34
+ 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.
35
+
36
+ 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.
26
37
 
27
38
  The production build performs an incremental sync:
28
39
 
29
40
  1. Next.js statically generates `/api/search/export` from the site's configured content sources.
30
41
  2. `geistdocs search sync` uploads new or changed Markdown documents to the site's Mixedbread Store.
31
- 3. Ask AI queries the Store by `siteId` and locale.
32
- 4. Geistdocs falls back to the local Orama retriever if Mixedbread is unavailable or its credentials are missing at runtime.
33
-
34
- Pages with `internal: true` or `excludeFrom: [chat]` are omitted from the export and removed from the Store on the next successful sync.
42
+ 3. Ask AI, site search, or both query the Store by `siteId` and locale.
43
+ 4. Geistdocs answers from the local Orama index if Mixedbread is unavailable or its credentials are missing at runtime.
35
44
 
36
45
  ## Prerequisites
37
46
 
@@ -39,7 +48,7 @@ Before enabling Mixedbread retrieval, confirm that:
39
48
 
40
49
  - The Mixedbread Marketplace integration is installed on your Vercel team.
41
50
  - The consumer site has its own Vercel project.
42
- - The consumer repository uses a Geistdocs release that includes `geistdocs search sync` and `createSearchExportRoute`.
51
+ - The consumer repository uses a Geistdocs release that includes `geistdocs search sync` and `createSearchExportRoute`. Site search needs a release that includes `search.provider`.
43
52
  - `source.config.ts` enables `includeProcessedMarkdown`, as generated Geistdocs projects do by default.
44
53
  - `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.
45
54
 
@@ -74,7 +83,13 @@ vercel integration list --integration mixedbread
74
83
 
75
84
  ## Configure the consumer site
76
85
 
77
- Set a unique `siteId` and enable Mixedbread in the consumer repository's root `geistdocs.tsx` file:
86
+ 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.
87
+
88
+ 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.
89
+
90
+ ### Use Mixedbread for Ask AI
91
+
92
+ Set `ai.retrieval` in `geistdocs.tsx`:
78
93
 
79
94
  ```tsx title="geistdocs.tsx"
80
95
  import type {
@@ -88,7 +103,64 @@ export const ai = {
88
103
  } satisfies GeistdocsAIConfig;
89
104
  ```
90
105
 
91
- The generated `lib/geistdocs/config.tsx` spreads `ai` into the package config. Keep `MXBAI_API_KEY` and `MXBAI_STORE_ID` out of `geistdocs.tsx` because that config is available to client components.
106
+ The generated `lib/geistdocs/config.tsx` spreads `ai` into the package config.
107
+
108
+ ### Use Mixedbread for site search
109
+
110
+ Site search takes two edits. First, set `search.provider` in `geistdocs.tsx`:
111
+
112
+ ```tsx title="geistdocs.tsx"
113
+ import type {
114
+ GeistdocsSearchConfig,
115
+ } from "@vercel/geistdocs/config";
116
+
117
+ export const siteId = "my-product-docs";
118
+
119
+ export const search = {
120
+ provider: "mixedbread",
121
+ } satisfies GeistdocsSearchConfig;
122
+ ```
123
+
124
+ Second, make sure `lib/geistdocs/config.tsx` imports `search` and passes it to `defineConfig`:
125
+
126
+ ```tsx title="lib/geistdocs/config.tsx"
127
+ import { defineConfig } from "@vercel/geistdocs/config";
128
+ import {
129
+ // ...your other exports
130
+ search,
131
+ siteId,
132
+ } from "@/geistdocs";
133
+
134
+ export const config = defineConfig({
135
+ // ...
136
+ search,
137
+ siteId,
138
+ });
139
+ ```
140
+
141
+ 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.
142
+
143
+ The search route file doesn't change. `createSearchRoute({ config, sources })` reads `search.provider` from `config`, and `search.enabled` keeps its existing meaning.
144
+
145
+ ### Override the connection on the server
146
+
147
+ 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`:
148
+
149
+ ```ts title="app/api/search/route.ts"
150
+ import { createSearchRoute } from "@vercel/geistdocs/routes/search";
151
+ import { config } from "@/lib/geistdocs/config";
152
+ import { geistdocsSource } from "@/lib/geistdocs/source";
153
+
154
+ export const GET = createSearchRoute({
155
+ config,
156
+ sources: [geistdocsSource],
157
+ mixedbread: {
158
+ apiBaseUrl: "https://mixedbread.example.com/v1",
159
+ },
160
+ });
161
+ ```
162
+
163
+ 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.
92
164
 
93
165
  ## Add the export route to an existing site
94
166
 
@@ -107,6 +179,38 @@ export const { GET } = createSearchExportRoute({
107
179
 
108
180
  Pass every configured source in `sources` when the site has multiple sections or documentation versions.
109
181
 
182
+ ## Control which pages reach the Store
183
+
184
+ The export holds the pages of every surface that reads the Store:
185
+
186
+ | Configuration | Pages in the export |
187
+ | --- | --- |
188
+ | Only `ai.retrieval: "mixedbread"` | Chat-visible pages, as before |
189
+ | Only `search.provider: "mixedbread"` | Search-visible pages |
190
+ | Both | Pages visible to chat, search, or both |
191
+
192
+ Pages with `internal: true` are never exported. A page that leaves the export is removed from the Store on the next successful sync.
193
+
194
+ 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.
195
+
196
+ 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.
197
+
198
+ To keep a page out of the Store entirely, reject it with `filterPage` on the export route:
199
+
200
+ ```ts title="app/api/search/export/route.ts"
201
+ import { createSearchExportRoute } from "@vercel/geistdocs/routes/search-export";
202
+ import { config } from "@/lib/geistdocs/config";
203
+ import { geistdocsSource } from "@/lib/geistdocs/source";
204
+
205
+ export const { GET } = createSearchExportRoute({
206
+ config,
207
+ sources: [geistdocsSource],
208
+ filterPage: (page) => !page.url.includes("/internal"),
209
+ });
210
+ ```
211
+
212
+ 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.
213
+
110
214
  ## Sync after each production build
111
215
 
112
216
  New Geistdocs projects run the sync from their build script. For an existing site, update `package.json`:
@@ -119,7 +223,9 @@ New Geistdocs projects run the sync from their build script. For an existing sit
119
223
  }
120
224
  ```
121
225
 
122
- Deploy the site to production. The first production build uploads every chat-visible page. Later builds upload changed pages and remove stale pages while leaving unrelated Store files untouched.
226
+ 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.
227
+
228
+ 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.`
123
229
 
124
230
  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:
125
231
 
@@ -129,14 +235,64 @@ vercel env run --environment production -- \
129
235
  pnpm exec geistdocs search sync --allow-non-production
130
236
  ```
131
237
 
132
- The sync command fails when Mixedbread retrieval is enabled 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.
238
+ 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.
239
+
240
+ 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.
241
+
242
+ ## Preview and local deployments
243
+
244
+ 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.
245
+
246
+ 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.
247
+
248
+ 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.
249
+
250
+ ## What readers see in site search
251
+
252
+ 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.
253
+
254
+ 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"`.
255
+
256
+ ## When local search answers instead
257
+
258
+ Site search never fails because of Mixedbread. The search route answers from the local index with status 200 when:
259
+
260
+ - `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.`
261
+ - 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.
262
+ - Mixedbread returns nothing that the deployment can show, for example before the first production sync.
263
+
264
+ The local route always answers these requests without calling Mixedbread:
265
+
266
+ - A request with an empty query.
267
+ - A request with a `tag` parameter. The built-in local index still returns no results for a tagged request, as before.
268
+ - A request for a locale the site does not configure.
133
269
 
134
270
  ## Verify retrieval
135
271
 
136
- Open the Mixedbread dashboard through Vercel and confirm that the Store contains one file per chat-visible documentation page:
272
+ Open the Mixedbread dashboard through Vercel and confirm that the Store contains one file per exported documentation page:
137
273
 
138
274
  ```bash title="Terminal"
139
275
  vercel integration open mixedbread
140
276
  ```
141
277
 
278
+ ### Verify Ask AI
279
+
142
280
  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.
281
+
282
+ ### Verify site search
283
+
284
+ Every search response from a site with `search.provider: "mixedbread"` carries the `x-geistdocs-search-provider` header. Request a query and read the header:
285
+
286
+ ```bash title="Terminal"
287
+ curl -si 'https://docs.example.com/api/search?query=deploy%20a%20site&locale=en'
288
+ ```
289
+
290
+ | Header value | Meaning |
291
+ | --- | --- |
292
+ | `mixedbread` | Mixedbread ranked the results. |
293
+ | `local` | The site opted in, but local search answered this request. Check the server logs for a warning. |
294
+ | 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`. |
295
+
296
+ ## Request cost
297
+
298
+ 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.
@@ -23,6 +23,9 @@ The provider handles these behaviors:
23
23
  2. **Analytics**: Integrates Vercel Analytics and Speed Insights when the local adapter includes them.
24
24
  3. **Search**: Configures the search dialog and connects it to your search API.
25
25
  4. **Ask AI**: Provides the client state used by the chat sidebar and page actions.
26
+ 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.
27
+
28
+ 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.
26
29
 
27
30
  ## Usage
28
31
 
@@ -2,6 +2,7 @@ import type {
2
2
  GeistdocsAgentReadinessConfig,
3
3
  GeistdocsAIConfig,
4
4
  GeistdocsNavbarBrand,
5
+ GeistdocsSearchConfig,
5
6
  } from "@vercel/geistdocs/config";
6
7
 
7
8
  export const navbarBrand: GeistdocsNavbarBrand = "vercel";
@@ -50,6 +51,8 @@ export const ai = {
50
51
  ),
51
52
  } satisfies GeistdocsAIConfig;
52
53
 
54
+ export const search = {} satisfies GeistdocsSearchConfig;
55
+
53
56
  export const agent = {
54
57
  product: {
55
58
  name: "Geistdocs",
@@ -88,7 +91,9 @@ export const translations = {
88
91
  export const basePath: string | undefined = undefined;
89
92
 
90
93
  /**
91
- * Unique identifier for this site, used in markdown request tracking analytics.
94
+ * Unique identifier for this site. Labels markdown request tracking analytics
95
+ * and feedback, and partitions the Mixedbread Store when `ai.retrieval` or
96
+ * `search.provider` is `"mixedbread"`, both of which require it.
92
97
  * Each site using geistdocs should set this to a unique value (e.g. "ai-sdk-docs", "next-docs").
93
98
  */
94
99
  export const siteId: string | undefined = undefined;
@@ -8,6 +8,7 @@ import {
8
8
  nav,
9
9
  navbarBrand,
10
10
  prompt,
11
+ search,
11
12
  siteId,
12
13
  suggestions,
13
14
  title,
@@ -24,6 +25,7 @@ export const config = defineConfig({
24
25
  nav,
25
26
  navbarBrand,
26
27
  basePath,
28
+ search,
27
29
  siteId,
28
30
  siteUrl: isSiteUrlConfigured ? siteUrl.toString() : undefined,
29
31
  translations,
@@ -17,7 +17,7 @@
17
17
  "@streamdown/code": "^1.0.1",
18
18
  "@vercel/agent-readability": "^0.7.0",
19
19
  "@vercel/analytics": "^1.6.1",
20
- "@vercel/geistdocs": "2.14.6",
20
+ "@vercel/geistdocs": "2.14.7-canary.6ce58a6",
21
21
  "@vercel/speed-insights": "^1.3.1",
22
22
  "ai": "^6.0.132",
23
23
  "clsx": "^2.1.1",