@vercel/geistdocs 1.25.2 → 1.26.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/cli.js +8 -0
- package/dist/cli/index.js +6 -2
- package/dist/config.d.ts +5 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/internal/chat-retrieval.d.ts +32 -0
- package/dist/internal/chat-retrieval.d.ts.map +1 -0
- package/dist/internal/chat-retrieval.js +91 -0
- package/dist/internal/mixedbread.d.ts +93 -0
- package/dist/internal/mixedbread.d.ts.map +1 -0
- package/dist/internal/mixedbread.js +286 -0
- package/dist/internal/page-actions-client.d.ts.map +1 -1
- package/dist/internal/page-actions-client.js +1 -19
- package/dist/internal/search-export.d.ts +18 -0
- package/dist/internal/search-export.d.ts.map +1 -0
- package/dist/internal/search-export.js +1 -0
- package/dist/internal/search-sync.d.ts +25 -0
- package/dist/internal/search-sync.d.ts.map +1 -0
- package/dist/internal/search-sync.js +312 -0
- package/dist/routes/chat.d.ts +8 -2
- package/dist/routes/chat.d.ts.map +1 -1
- package/dist/routes/chat.js +53 -15
- package/dist/routes/search-export.d.ts +12 -0
- package/dist/routes/search-export.d.ts.map +1 -0
- package/dist/routes/search-export.js +44 -0
- package/docs/agents.md +4 -3
- package/docs/llms.txt +384 -33
- package/docs/manifest.json +12 -3
- package/docs/pages/ask-ai.md +3 -0
- package/docs/pages/configuration.md +5 -2
- package/docs/pages/deployment.md +30 -5
- package/docs/pages/env.md +13 -3
- package/docs/pages/getting-started.md +29 -9
- package/docs/pages/index.md +3 -2
- package/docs/pages/md.md +1 -1
- package/docs/pages/migration.md +148 -8
- package/docs/pages/mixedbread-retrieval.md +144 -0
- package/docs/sitemap.md +3 -2
- package/package.json +10 -4
- package/template/.env.example +19 -0
- package/template/AGENTS.md +17 -3
- package/template/app/api/search/export/route.ts +8 -0
- package/template/content/docs/ask-ai.mdx +3 -0
- package/template/content/docs/configuration.mdx +5 -2
- package/template/content/docs/deployment.mdx +31 -6
- package/template/content/docs/env.mdx +14 -4
- package/template/content/docs/getting-started.mdx +30 -10
- package/template/content/docs/index.mdx +3 -2
- package/template/content/docs/md.mdx +1 -1
- package/template/content/docs/meta.json +1 -0
- package/template/content/docs/migration.mdx +150 -9
- package/template/content/docs/mixedbread-retrieval.mdx +142 -0
- package/template/geistdocs.tsx +12 -1
- package/template/lib/geistdocs/config.tsx +2 -5
- package/template/package.json +2 -2
package/docs/manifest.json
CHANGED
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"description": "Learn about the environment variables used in Geistdocs",
|
|
31
31
|
"path": "pages/env.md",
|
|
32
32
|
"source": "apps/template/content/docs/env.mdx",
|
|
33
|
-
"summary": "Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.",
|
|
33
|
+
"summary": "Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, and production URL configuration.",
|
|
34
34
|
"title": "Environment Variables",
|
|
35
35
|
"type": "reference",
|
|
36
36
|
"url": "/docs/env"
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
"description": "Learn how to deploy your Geistdocs site to Vercel",
|
|
40
40
|
"path": "pages/deployment.md",
|
|
41
41
|
"source": "apps/template/content/docs/deployment.mdx",
|
|
42
|
-
"summary": "Deploy
|
|
42
|
+
"summary": "Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.",
|
|
43
43
|
"title": "Deploy to Vercel",
|
|
44
44
|
"type": "guide",
|
|
45
45
|
"url": "/docs/deployment"
|
|
@@ -152,6 +152,15 @@
|
|
|
152
152
|
"type": "integration",
|
|
153
153
|
"url": "/docs/feedback"
|
|
154
154
|
},
|
|
155
|
+
{
|
|
156
|
+
"description": "Configure Mixedbread retrieval for a Geistdocs Ask AI chat and sync documentation to a site-specific Store",
|
|
157
|
+
"path": "pages/mixedbread-retrieval.md",
|
|
158
|
+
"source": "apps/template/content/docs/mixedbread-retrieval.mdx",
|
|
159
|
+
"summary": "Provision a Mixedbread Store for one Geistdocs consumer site, enable semantic retrieval, and sync documentation during production builds.",
|
|
160
|
+
"title": "Improve Ask AI answers with Mixedbread",
|
|
161
|
+
"type": "guide",
|
|
162
|
+
"url": "/docs/mixedbread-retrieval"
|
|
163
|
+
},
|
|
155
164
|
{
|
|
156
165
|
"description": "Add multi-language support to your documentation site",
|
|
157
166
|
"path": "pages/internationalization.md",
|
|
@@ -208,5 +217,5 @@
|
|
|
208
217
|
}
|
|
209
218
|
],
|
|
210
219
|
"source": "apps/template/content/docs",
|
|
211
|
-
"version": "1.
|
|
220
|
+
"version": "1.26.0"
|
|
212
221
|
}
|
package/docs/pages/ask-ai.md
CHANGED
|
@@ -10,6 +10,7 @@ prerequisites:
|
|
|
10
10
|
related:
|
|
11
11
|
- /docs/open-in-chat
|
|
12
12
|
- /docs/llms-txt
|
|
13
|
+
- /docs/mixedbread-retrieval
|
|
13
14
|
- /docs/configuration
|
|
14
15
|
---
|
|
15
16
|
|
|
@@ -174,6 +175,8 @@ By default, the AI assistant includes a built-in `search_docs` tool that:
|
|
|
174
175
|
|
|
175
176
|
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.
|
|
176
177
|
|
|
178
|
+
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 and the visible search dialog remain unchanged. Geistdocs falls back to local Orama retrieval when Mixedbread is unavailable. Read [Improve Ask AI answers with Mixedbread](/docs/mixedbread-retrieval) to provision a Store and configure production sync.
|
|
179
|
+
|
|
177
180
|
### Persistent Chat History
|
|
178
181
|
|
|
179
182
|
Conversations are automatically saved to the browser's IndexedDB, providing:
|
|
@@ -116,6 +116,7 @@ On desktop, the group opens as a full-width panel below the navbar, following th
|
|
|
116
116
|
import { defineConfig } from "@vercel/geistdocs/config";
|
|
117
117
|
import {
|
|
118
118
|
agent,
|
|
119
|
+
ai,
|
|
119
120
|
basePath,
|
|
120
121
|
github,
|
|
121
122
|
Logo,
|
|
@@ -140,6 +141,7 @@ export const config = defineConfig({
|
|
|
140
141
|
ai: {
|
|
141
142
|
prompt,
|
|
142
143
|
suggestions,
|
|
144
|
+
...ai,
|
|
143
145
|
},
|
|
144
146
|
});
|
|
145
147
|
```
|
|
@@ -170,15 +172,16 @@ export const config = defineConfig({
|
|
|
170
172
|
});
|
|
171
173
|
```
|
|
172
174
|
|
|
173
|
-
The `ai` config
|
|
175
|
+
The `ai` config accepts `retrieval: "mixedbread"` to use semantic documentation retrieval and `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
|
|
174
176
|
|
|
175
177
|
```tsx title="geistdocs.tsx"
|
|
176
178
|
export const ai = {
|
|
179
|
+
retrieval: "mixedbread",
|
|
177
180
|
eveAgent: { url: "https://help-eve.example.dev" },
|
|
178
181
|
};
|
|
179
182
|
```
|
|
180
183
|
|
|
181
|
-
See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication.
|
|
184
|
+
See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication. Read [Improve Ask AI answers with Mixedbread](/docs/mixedbread-retrieval) before enabling semantic retrieval.
|
|
182
185
|
|
|
183
186
|
Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
|
|
184
187
|
|
package/docs/pages/deployment.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
title: Deploy to Vercel
|
|
3
3
|
description: Learn how to deploy your Geistdocs site to Vercel
|
|
4
4
|
type: guide
|
|
5
|
-
summary: Deploy
|
|
5
|
+
summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
|
|
6
6
|
url: /docs/deployment
|
|
7
7
|
source: apps/template/content/docs/deployment.mdx
|
|
8
8
|
prerequisites:
|
|
@@ -14,9 +14,9 @@ related:
|
|
|
14
14
|
|
|
15
15
|
# Deploy to Vercel
|
|
16
16
|
|
|
17
|
-
Deploy a Geistdocs site to Vercel as a Next.js app.
|
|
17
|
+
Deploy a Geistdocs site to Vercel as a Next.js app. Configure package access, environment variables, and the production URL before shipping.
|
|
18
18
|
|
|
19
|
-
Help me deploy this Geistdocs project to Vercel. Check
|
|
19
|
+
Help me deploy this Geistdocs project to Vercel. Check whether it uses the Geistcn canary and therefore needs private npm access, then review the package scripts, environment variables, GitHub Actions authentication, and Vercel project settings.
|
|
20
20
|
|
|
21
21
|
## Prerequisites
|
|
22
22
|
|
|
@@ -26,6 +26,31 @@ Before deploying, you need:
|
|
|
26
26
|
- A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
|
|
27
27
|
- Your Vercel account connected to your GitHub account
|
|
28
28
|
- Environment variables ready (see [Environment Variables](/docs/env))
|
|
29
|
+
- Access to restricted `@vercel` npm packages if the project uses the Geistcn canary
|
|
30
|
+
|
|
31
|
+
## Configure private package access
|
|
32
|
+
|
|
33
|
+
The Geistcn canary depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Package installation fails without npm authentication.
|
|
34
|
+
|
|
35
|
+
For a Vercel deployment, ask `#help-core-platform` to add your Vercel project to the shared `NPM_TOKEN` environment variable list. Include the project link and the environments that need access. When `NPM_TOKEN` is available, Vercel creates the npm authentication configuration before installing dependencies. Do not copy the shared token into your repository or project documentation.
|
|
36
|
+
|
|
37
|
+
For GitHub Actions, ask `#help-it` to add your repository to the allowlist for the `NPM_TOKEN` organization secret. Pass that secret to npm authentication during the install job:
|
|
38
|
+
|
|
39
|
+
```yaml title=".github/workflows/check.yml"
|
|
40
|
+
- uses: pnpm/action-setup@v4
|
|
41
|
+
|
|
42
|
+
- uses: actions/setup-node@v4
|
|
43
|
+
with:
|
|
44
|
+
node-version: 20
|
|
45
|
+
cache: pnpm
|
|
46
|
+
registry-url: https://registry.npmjs.org
|
|
47
|
+
|
|
48
|
+
- run: pnpm install
|
|
49
|
+
env:
|
|
50
|
+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Read [How do I use private dependencies with Vercel?](https://vercel.com/kb/guide/using-private-dependencies-with-vercel) for the platform's npm authentication behavior.
|
|
29
54
|
|
|
30
55
|
## Deploy to Vercel
|
|
31
56
|
|
|
@@ -35,9 +60,9 @@ To deploy from the Vercel dashboard:
|
|
|
35
60
|
2. Select your Geistdocs repository
|
|
36
61
|
3. Configure your project settings:
|
|
37
62
|
- **Framework Preset**: Next.js (automatically detected)
|
|
38
|
-
- **Build Command**: `pnpm build`
|
|
63
|
+
- **Build Command**: `pnpm build`
|
|
39
64
|
- **Output Directory**: `.next` (default)
|
|
40
|
-
- **Install Command**: `pnpm install`
|
|
65
|
+
- **Install Command**: `pnpm install`
|
|
41
66
|
4. Add your environment variables (see [Environment Variables](/docs/env))
|
|
42
67
|
5. Click "Deploy"
|
|
43
68
|
|
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, proxy mode, and production URL configuration.
|
|
5
|
+
summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, and production URL configuration.
|
|
6
6
|
url: /docs/env
|
|
7
7
|
source: apps/template/content/docs/env.mdx
|
|
8
8
|
prerequisites:
|
|
@@ -14,9 +14,9 @@ related:
|
|
|
14
14
|
|
|
15
15
|
# Environment Variables
|
|
16
16
|
|
|
17
|
-
Geistdocs uses environment variables to configure Ask AI, optional Vertex-backed proxy mode, and production URL behavior.
|
|
17
|
+
Geistdocs uses environment variables to configure Ask AI, optional Mixedbread retrieval, optional Vertex-backed proxy mode, and production URL behavior.
|
|
18
18
|
|
|
19
|
-
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.
|
|
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`, 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
|
|
|
21
21
|
## `AI_GATEWAY_API_KEY`
|
|
22
22
|
|
|
@@ -26,6 +26,16 @@ The API key for the AI Gateway. This is used to power the default local AI chat
|
|
|
26
26
|
|
|
27
27
|
Leave `GEISTDOCS_CHAT_PROXY_URL` unset to use AI Gateway mode.
|
|
28
28
|
|
|
29
|
+
## `MXBAI_API_KEY`
|
|
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.
|
|
32
|
+
|
|
33
|
+
## `MXBAI_STORE_ID`
|
|
34
|
+
|
|
35
|
+
The Mixedbread Store used by one consumer site. Set `ai.retrieval` to `"mixedbread"` and configure a unique `siteId` before using this value.
|
|
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 answers with Mixedbread](/docs/mixedbread-retrieval) for the complete setup.
|
|
38
|
+
|
|
29
39
|
## `GEISTDOCS_CHAT_PROXY_URL`
|
|
30
40
|
|
|
31
41
|
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.
|
|
@@ -16,35 +16,55 @@ related:
|
|
|
16
16
|
|
|
17
17
|
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.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Help me create a Geistdocs project. Use `@vercel/geistdocs@latest` for the stable release or `@vercel/geistdocs@canary` when I specifically need the Geistcn migration. Then 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`.
|
|
20
20
|
|
|
21
21
|
## Prerequisites
|
|
22
22
|
|
|
23
23
|
Before you begin, install:
|
|
24
24
|
|
|
25
|
-
- Node.js
|
|
26
|
-
- pnpm
|
|
25
|
+
- Node.js 20.9 or later
|
|
26
|
+
- pnpm
|
|
27
27
|
- Git
|
|
28
28
|
|
|
29
|
+
The Geistdocs CLI always uses pnpm to install the generated project's dependencies. Running the CLI through `npx` does not remove the pnpm requirement.
|
|
30
|
+
|
|
31
|
+
## Choose a release channel
|
|
32
|
+
|
|
33
|
+
Use `@vercel/geistdocs@latest` for the current stable package-backed release. Use `@vercel/geistdocs@canary` only when you need changes being evaluated on the `canary` branch, including the current Geistcn migration.
|
|
34
|
+
|
|
35
|
+
The canary dist-tag can move several times in one day. The CLI resolves the tag once and writes that exact version to the generated `package.json`.
|
|
36
|
+
|
|
37
|
+
## Authenticate for the Geistcn canary
|
|
38
|
+
|
|
39
|
+
The Geistcn canary depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Configure npm authentication before running the canary CLI. Add this configuration to your user-level `~/.npmrc`:
|
|
40
|
+
|
|
41
|
+
```ini title="~/.npmrc"
|
|
42
|
+
@vercel:registry=https://registry.npmjs.org/
|
|
43
|
+
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
|
|
44
|
+
always-auth=true
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Set `NPM_TOKEN` from an approved internal source and keep its value out of files and Git. Stable Geistdocs does not currently require these restricted packages. Read [Deploy to Vercel](/docs/deployment) before configuring automated installs.
|
|
48
|
+
|
|
29
49
|
## Create a project
|
|
30
50
|
|
|
31
|
-
Run the Geistdocs CLI from an empty parent folder:
|
|
51
|
+
Run the Geistdocs CLI from an empty parent folder. For stable Geistdocs, run:
|
|
32
52
|
|
|
33
53
|
```bash title="Terminal"
|
|
34
|
-
pnpm dlx @vercel/geistdocs init --name my-docs
|
|
54
|
+
pnpm dlx @vercel/geistdocs@latest init --name my-docs
|
|
35
55
|
```
|
|
36
56
|
|
|
37
|
-
|
|
57
|
+
For the Geistcn canary, run:
|
|
38
58
|
|
|
39
59
|
```bash title="Terminal"
|
|
40
|
-
|
|
60
|
+
pnpm dlx @vercel/geistdocs@canary init --name my-docs
|
|
41
61
|
```
|
|
42
62
|
|
|
43
63
|
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.
|
|
44
64
|
|
|
45
65
|
## Understand generated dependencies
|
|
46
66
|
|
|
47
|
-
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.
|
|
67
|
+
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. Canary projects also declare the matching `@vercel/geistcn` and `@vercel/geistcn-assets` versions directly because generated application files import them.
|
|
48
68
|
|
|
49
69
|
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.
|
|
50
70
|
|
|
@@ -109,7 +129,7 @@ Read [Configuration](/docs/configuration) for the full configuration surface.
|
|
|
109
129
|
|
|
110
130
|
## Update Geistdocs
|
|
111
131
|
|
|
112
|
-
For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files.
|
|
132
|
+
For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files. Projects already using a canary version continue to follow the `canary` dist-tag; stable projects follow `latest`.
|
|
113
133
|
|
|
114
134
|
```bash title="Terminal"
|
|
115
135
|
pnpm exec geistdocs update
|
package/docs/pages/index.md
CHANGED
|
@@ -28,7 +28,7 @@ Geistdocs has three main parts:
|
|
|
28
28
|
```mermaid
|
|
29
29
|
flowchart TB
|
|
30
30
|
subgraph Package["@vercel/geistdocs package"]
|
|
31
|
-
cli["CLI: init, update, translate"]
|
|
31
|
+
cli["CLI: init, update, translate, search sync"]
|
|
32
32
|
runtime["Runtime: layout, routes, MDX, controls"]
|
|
33
33
|
bundledTemplate["Bundled template snapshot"]
|
|
34
34
|
end
|
|
@@ -78,6 +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
82
|
- Page actions, including feedback, copy page, open in chat, and edit on GitHub
|
|
82
83
|
- Agent-readiness metadata with `/agents.md` and `/.well-known/mcp.json`
|
|
83
84
|
- Raw Markdown routes for AI tools
|
|
@@ -87,7 +88,7 @@ Advanced projects can use package APIs for versioned docs, multiple content sour
|
|
|
87
88
|
- RSS feed
|
|
88
89
|
- Theme-aware images
|
|
89
90
|
- Internationalized routes
|
|
90
|
-
- CLI commands for init, update, and
|
|
91
|
+
- CLI commands for init, update, translation, and Mixedbread search sync
|
|
91
92
|
|
|
92
93
|
## Next steps
|
|
93
94
|
|
package/docs/pages/md.md
CHANGED
|
@@ -39,7 +39,7 @@ The `.mdx` version returns:
|
|
|
39
39
|
|
|
40
40
|
For a docs section mounted at `/docs`, the section root remains `/docs.md`. For a source mounted at the app root with `baseUrl: "/"`, Geistdocs uses `/index.md` for the root page. If Next.js has `basePath: "/docs"`, that public root Markdown URL is `/docs/index.md`.
|
|
41
41
|
|
|
42
|
-
Copy Page, View as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
|
|
42
|
+
Copy Page, View as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. View as Markdown opens the resolved `.md` URL in a new tab from a button, which keeps the URL shareable without adding an anchor to the page. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
|
|
43
43
|
|
|
44
44
|
## Use cases
|
|
45
45
|
|
package/docs/pages/migration.md
CHANGED
|
@@ -18,7 +18,10 @@ related:
|
|
|
18
18
|
|
|
19
19
|
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.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
> Note:
|
|
22
|
+
The current Geistcn migration is available from the `canary` dist-tag, not `latest`. The canary depends on restricted `@vercel/geistcn` packages and is intended for Vercel-internal projects while the migration is evaluated.
|
|
23
|
+
|
|
24
|
+
Help me migrate this existing docs site to package-backed Geistdocs. First determine whether I should use the stable release or the Geistcn canary. 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. For the Geistcn canary, also inspect package authentication, `@vercel/geistdocs` component and asset imports, root HTML classes, and Next.js configuration. Pin the selected version and use package APIs without copying package internals.
|
|
22
25
|
|
|
23
26
|
## Before you migrate
|
|
24
27
|
|
|
@@ -30,6 +33,7 @@ Create a working branch and inventory the current site before replacing code:
|
|
|
30
33
|
- Static files that overlap package routes, such as `public/llms.txt`.
|
|
31
34
|
- Search, chat, `llms.txt`, page-level Markdown, `sitemap.md`, `agents.md`, `/.well-known/mcp.json`, RSS, and Open Graph routes.
|
|
32
35
|
- Tailwind CSS version and custom plugins.
|
|
36
|
+
- Imports from `@vercel/geistdocs/components/*` or `@vercel/geistdocs/assets/*` that the Geistcn canary removes.
|
|
33
37
|
- Direct app usage of `ai` or `@ai-sdk/react` outside Geistdocs.
|
|
34
38
|
- Environment variables required by the homepage, docs routes, or API routes.
|
|
35
39
|
|
|
@@ -44,20 +48,76 @@ Fix unrelated build failures first. A migration is safer when the starting point
|
|
|
44
48
|
|
|
45
49
|
## Install Geistdocs
|
|
46
50
|
|
|
47
|
-
|
|
51
|
+
For the current stable package-backed release, install `latest` and record the exact resolved version:
|
|
52
|
+
|
|
53
|
+
```bash title="Terminal"
|
|
54
|
+
pnpm add --save-exact @vercel/geistdocs@latest
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Geistdocs requires Node.js 20.9 or later and Next.js 16.3.3 or later within 16.x. Earlier 16.3 releases can retain an optional catch-all route's index content after a client navigation to a child page when Cache Components and Partial Prefetching are enabled.
|
|
58
|
+
|
|
59
|
+
If you are starting from a generated stable Geistdocs project and moving content into it, run the CLI from an empty parent folder:
|
|
60
|
+
|
|
61
|
+
```bash title="Terminal"
|
|
62
|
+
pnpm dlx @vercel/geistdocs@latest init --name my-docs
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Install the Geistcn canary
|
|
66
|
+
|
|
67
|
+
The Geistcn canary requires npm access to restricted `@vercel` packages. Configure your user-level npm authentication before installation:
|
|
68
|
+
|
|
69
|
+
```ini title="~/.npmrc"
|
|
70
|
+
@vercel:registry=https://registry.npmjs.org/
|
|
71
|
+
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
|
|
72
|
+
always-auth=true
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Set `NPM_TOKEN` from an approved internal source and keep its value out of files and Git. Read [Deploy to Vercel](/docs/deployment#configure-private-package-access) for Vercel and GitHub Actions access.
|
|
76
|
+
|
|
77
|
+
For an existing standalone project, install the canary and the direct Geistcn dependencies used by application files. The current canary template uses `@vercel/geistcn` 1.0.3 and `@vercel/geistcn-assets` 2.0.1:
|
|
78
|
+
|
|
79
|
+
```bash title="Terminal"
|
|
80
|
+
pnpm add --save-exact \
|
|
81
|
+
@vercel/geistdocs@canary \
|
|
82
|
+
@vercel/geistcn@1.0.3 \
|
|
83
|
+
@vercel/geistcn-assets@2.0.1
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`--save-exact` records the canary resolved at install time instead of a range. Before upgrading later, check the next canary and test that exact version:
|
|
87
|
+
|
|
88
|
+
```bash title="Terminal"
|
|
89
|
+
npm view @vercel/geistdocs dist-tags.canary
|
|
90
|
+
```
|
|
48
91
|
|
|
49
|
-
|
|
92
|
+
In a monorepo that owns the Geistcn packages, such as `vercel/front`, keep their existing `workspace:*` dependency specifications and pin only `@vercel/geistdocs` to the tested canary.
|
|
93
|
+
|
|
94
|
+
If you are starting from a generated Geistdocs project and moving content into it, run the canary CLI from an empty parent folder:
|
|
50
95
|
|
|
51
96
|
```bash title="Terminal"
|
|
52
|
-
pnpm
|
|
97
|
+
pnpm dlx @vercel/geistdocs@canary init --name my-docs
|
|
53
98
|
```
|
|
54
99
|
|
|
55
|
-
|
|
100
|
+
## Replace imports for the Geistcn canary
|
|
101
|
+
|
|
102
|
+
The Geistcn canary removes generic design-system components and assets from the Geistdocs public API. Search for affected imports before upgrading:
|
|
56
103
|
|
|
57
104
|
```bash title="Terminal"
|
|
58
|
-
|
|
105
|
+
rg '@vercel/geistdocs/(components|assets)' .
|
|
59
106
|
```
|
|
60
107
|
|
|
108
|
+
Replace imports according to this table:
|
|
109
|
+
|
|
110
|
+
| Previous Geistdocs import | Replacement |
|
|
111
|
+
| --- | --- |
|
|
112
|
+
| `components/badge`, `components/button`, `components/dialog`, `components/drawer`, `components/input`, `components/kbd`, `components/separator`, `components/sheet`, `components/spinner`, `components/textarea`, `components/theme-switcher`, or `components/tooltip` | Import the matching component directly from `@vercel/geistcn/components/<name>`. |
|
|
113
|
+
| `components/switch` | Import toggle controls from `@vercel/geistcn/components/toggle`. |
|
|
114
|
+
| `components/sonner` | Use `Toasts` and `useToasts` from `@vercel/geistcn/components/toasts`. |
|
|
115
|
+
| `components/theme-aware-image` | Use `Image` from `@vercel/geistcn/components/image` with `srcLight` and `srcDark`. |
|
|
116
|
+
| `assets/icons`, `assets/icons/*`, `assets/logos`, or `assets/logos/*` | Import from `@vercel/geistcn-assets/icons`, `@vercel/geistcn-assets/icons/*`, `@vercel/geistcn-assets/logos`, or `@vercel/geistcn-assets/logos/*`. |
|
|
117
|
+
| `components/button-group`, `components/card`, or `components/input-group` | Use an appropriate Geistcn component or keep an application-owned composition. There is no direct Geistcn replacement with the same API. |
|
|
118
|
+
|
|
119
|
+
Keep documentation-specific composites such as `Callout`, `CodeBlock`, `CodeBlockTabs`, `CommandPrompt`, `CopyPrompt`, and `Mermaid` imported from `@vercel/geistdocs/components/*`.
|
|
120
|
+
|
|
61
121
|
## Configure Next.js
|
|
62
122
|
|
|
63
123
|
The Geistdocs Next.js integration composes Fumadocs MDX, enables automatic app-route discovery for agent-readable 404s, and preserves your Next.js configuration. Enable Cache Components in the same file:
|
|
@@ -76,6 +136,39 @@ const config: NextConfig = {
|
|
|
76
136
|
export default withGeistdocs(config);
|
|
77
137
|
```
|
|
78
138
|
|
|
139
|
+
### Configure Next.js for the Geistcn canary
|
|
140
|
+
|
|
141
|
+
Geistcn publishes TypeScript source from supporting packages. A project using the Geistcn canary also needs the matching transpilation and modular import settings:
|
|
142
|
+
|
|
143
|
+
```ts title="next.config.ts"
|
|
144
|
+
import { createGeistdocs } from "@vercel/geistdocs/next";
|
|
145
|
+
import type { NextConfig } from "next";
|
|
146
|
+
|
|
147
|
+
const withGeistdocs = createGeistdocs();
|
|
148
|
+
|
|
149
|
+
const config: NextConfig = {
|
|
150
|
+
modularizeImports: {
|
|
151
|
+
"@vercel/geistcn/components": {
|
|
152
|
+
skipDefaultConversion: true,
|
|
153
|
+
transform: "@vercel/geistcn/components/{{ kebabCase member }}",
|
|
154
|
+
},
|
|
155
|
+
"@vercel/geistcn/core": {
|
|
156
|
+
skipDefaultConversion: true,
|
|
157
|
+
transform: "@vercel/geistcn/core",
|
|
158
|
+
},
|
|
159
|
+
},
|
|
160
|
+
transpilePackages: [
|
|
161
|
+
"@vercel/geistcn",
|
|
162
|
+
"@vercel/geist-test-utils",
|
|
163
|
+
"@vercel/next-themes",
|
|
164
|
+
],
|
|
165
|
+
cacheComponents: true,
|
|
166
|
+
partialPrefetching: true,
|
|
167
|
+
};
|
|
168
|
+
|
|
169
|
+
export default withGeistdocs(config);
|
|
170
|
+
```
|
|
171
|
+
|
|
79
172
|
Restart `next dev` after adding, deleting, or renaming an App Router page or route. Production builds always regenerate the route manifest.
|
|
80
173
|
|
|
81
174
|
Every root dynamic parameter needs at least one value from `generateStaticParams`. For a site with a `[lang]` root segment, return every configured language from the root layout:
|
|
@@ -104,6 +197,33 @@ Keep `partialPrefetching` enabled so links reuse each route's static and cached
|
|
|
104
197
|
|
|
105
198
|
For unknown HTML pages, browsers can receive the docs loading shell with a `200` response before the page resolves to the not-found UI. Crawlers wait for the complete response and receive `404`. Machine-readable Markdown routes keep their configured status behavior.
|
|
106
199
|
|
|
200
|
+
## Configure the root layout for the Geistcn canary
|
|
201
|
+
|
|
202
|
+
Geistcn provides the fonts, theme classes, and Tailwind preflight used by the package UI. Apply them to the root `<html>` element:
|
|
203
|
+
|
|
204
|
+
```tsx title="app/[lang]/layout.tsx"
|
|
205
|
+
import { geistFontClasses } from "@vercel/geistcn/core";
|
|
206
|
+
import { cn } from "@vercel/geistcn/utils";
|
|
207
|
+
import type { ReactNode } from "react";
|
|
208
|
+
|
|
209
|
+
export default function RootLayout({ children }: { children: ReactNode }) {
|
|
210
|
+
return (
|
|
211
|
+
<html
|
|
212
|
+
className={cn(
|
|
213
|
+
geistFontClasses,
|
|
214
|
+
"tailwind tailwind-preflight antialiased"
|
|
215
|
+
)}
|
|
216
|
+
lang="en"
|
|
217
|
+
suppressHydrationWarning
|
|
218
|
+
>
|
|
219
|
+
<body>{children}</body>
|
|
220
|
+
</html>
|
|
221
|
+
);
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Keep the site's existing providers and metadata inside this structure. If the route has a `[lang]` parameter, use the active language instead of the hardcoded `en` value.
|
|
226
|
+
|
|
107
227
|
## Align Ask AI dependencies
|
|
108
228
|
|
|
109
229
|
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.
|
|
@@ -374,7 +494,7 @@ For a base-path application whose root page is documentation, add `"/"` to the s
|
|
|
374
494
|
|
|
375
495
|
## Configure Tailwind CSS
|
|
376
496
|
|
|
377
|
-
Tailwind CSS v4
|
|
497
|
+
Stable Geistdocs uses Tailwind CSS v4 with source entries for package components and related dependencies:
|
|
378
498
|
|
|
379
499
|
```css title="app/styles/geistdocs.css"
|
|
380
500
|
@import "tailwindcss";
|
|
@@ -388,6 +508,23 @@ Tailwind CSS v4 requires `@source` entries for package components and related de
|
|
|
388
508
|
|
|
389
509
|
Move Tailwind CSS v3 plugin utilities into CSS-first v4 utilities or theme variables. Keep custom token names stable while you migrate components.
|
|
390
510
|
|
|
511
|
+
### Configure Tailwind CSS for the Geistcn canary
|
|
512
|
+
|
|
513
|
+
For the Geistcn canary, use the import order and narrow Geistcn source scan from the canary template:
|
|
514
|
+
|
|
515
|
+
```css title="app/styles/geistdocs.css"
|
|
516
|
+
@import "@vercel/geistcn/tailwind.css";
|
|
517
|
+
@import "fumadocs-ui/css/shadcn.css";
|
|
518
|
+
@import "fumadocs-ui/css/preset.css";
|
|
519
|
+
@import "@vercel/geistdocs/theme.css";
|
|
520
|
+
@import "@vercel/geistcn/styles.css";
|
|
521
|
+
@import "@vercel/geistcn/marketing-typography.css";
|
|
522
|
+
|
|
523
|
+
@source "../../node_modules/@vercel/geistcn/src/components/**/*.{ts,tsx}";
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
Geistcn owns the Geist tokens, theme, typography, preflight, and animation utilities. The Geistdocs theme entry point contains documentation and Fumadocs integration rules and sources the compiled Geistdocs runtime. Do not scan all of `@vercel/geistcn/src`; font internals in the published package can reference paths outside the application root and cause Turbopack to fail.
|
|
527
|
+
|
|
391
528
|
## Handle environment variables
|
|
392
529
|
|
|
393
530
|
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.
|
|
@@ -398,7 +535,7 @@ export const flagsSecret =
|
|
|
398
535
|
(process.env.NODE_ENV === "development" ? "local-development-secret" : undefined);
|
|
399
536
|
```
|
|
400
537
|
|
|
401
|
-
Keep real secrets in `.env.local` and out of Git.
|
|
538
|
+
Keep real application secrets in `.env.local` and out of Git. `NPM_TOKEN` is an install-time credential, not an application environment variable. Keep it in your shell, Vercel project settings, or GitHub Actions secrets, and never prefix it with `NEXT_PUBLIC_`.
|
|
402
539
|
|
|
403
540
|
## Verify the migration
|
|
404
541
|
|
|
@@ -406,10 +543,13 @@ Run the same checks after each routing or source change:
|
|
|
406
543
|
|
|
407
544
|
```bash title="Terminal"
|
|
408
545
|
pnpm postinstall
|
|
546
|
+
pnpm list @vercel/geistdocs
|
|
409
547
|
pnpm build
|
|
410
548
|
pnpm dev
|
|
411
549
|
```
|
|
412
550
|
|
|
551
|
+
For the Geistcn canary, also run `pnpm list @vercel/geistcn @vercel/geistcn-assets` and confirm the versions match the selected canary template.
|
|
552
|
+
|
|
413
553
|
Check these URLs locally:
|
|
414
554
|
|
|
415
555
|
- `/docs` or the migrated docs root.
|