@vercel/geistdocs 1.25.1-canary.4e75e60 → 1.25.1-canary.6261418

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 (44) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/components/code-block-tabs.js +1 -1
  3. package/dist/components/code-block.d.ts.map +1 -1
  4. package/dist/components/code-block.js +1 -1
  5. package/dist/components/copy-prompt.js +1 -1
  6. package/dist/internal/chat/activity.d.ts +20 -0
  7. package/dist/internal/chat/activity.d.ts.map +1 -0
  8. package/dist/internal/chat/activity.js +43 -0
  9. package/dist/internal/chat/message-metadata.d.ts.map +1 -1
  10. package/dist/internal/chat/message-metadata.js +15 -30
  11. package/dist/internal/chat/message-sources.d.ts +3 -0
  12. package/dist/internal/chat/message-sources.d.ts.map +1 -0
  13. package/dist/internal/chat/message-sources.js +23 -0
  14. package/dist/internal/chat/message.d.ts.map +1 -1
  15. package/dist/internal/chat/message.js +35 -3
  16. package/dist/internal/chat/shell.d.ts.map +1 -1
  17. package/dist/internal/chat/shell.js +7 -2
  18. package/dist/internal/chat/source-chunks.d.ts +9 -0
  19. package/dist/internal/chat/source-chunks.d.ts.map +1 -0
  20. package/dist/internal/chat/source-chunks.js +7 -0
  21. package/dist/internal/search.js +1 -1
  22. package/dist/internal/sidebar-tree.d.ts.map +1 -1
  23. package/dist/internal/sidebar-tree.js +6 -1
  24. package/dist/routes/chat.d.ts.map +1 -1
  25. package/dist/routes/chat.js +30 -13
  26. package/dist/versions.js +2 -2
  27. package/docs/agents.md +4 -3
  28. package/docs/llms.txt +188 -23
  29. package/docs/manifest.json +12 -3
  30. package/docs/pages/deployment.md +30 -5
  31. package/docs/pages/getting-started.md +38 -12
  32. package/docs/pages/guides/nested-navigation.md +1 -1
  33. package/docs/pages/migration-2.md +106 -0
  34. package/docs/pages/migration.md +5 -2
  35. package/docs/sitemap.md +3 -2
  36. package/package.json +3 -4
  37. package/template/content/docs/deployment.mdx +31 -6
  38. package/template/content/docs/getting-started.mdx +39 -13
  39. package/template/content/docs/guides/nested-navigation.mdx +1 -1
  40. package/template/content/docs/meta.json +1 -0
  41. package/template/content/docs/migration-2.mdx +106 -0
  42. package/template/content/docs/migration.mdx +5 -1
  43. package/template/package.json +3 -3
  44. package/theme.css +0 -4
@@ -0,0 +1,106 @@
1
+ ---
2
+ title: Migrate from Geistdocs 1.x to 2.0
3
+ description: Upgrade imports, dependencies, and routing without copying Geistdocs internals
4
+ type: guide
5
+ summary: A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.
6
+ url: /docs/migration-2
7
+ source: apps/template/content/docs/migration-2.mdx
8
+ related:
9
+ - /docs/migration
10
+ - /docs/configuration
11
+ - /docs/versioned-docs
12
+ - /docs/proxy
13
+ ---
14
+
15
+ # Migrate from Geistdocs 1.x to 2.0
16
+
17
+ Use this guide only for a site already running Geistdocs 1.x. Geistdocs 2.0 moves shared UI primitives and assets to Geistcn; its package-backed page, source, search, chat, proxy, and agent-readable route APIs remain the preferred integration.
18
+
19
+ Upgrade this Geistdocs site from 1.x to 2.0. Inspect `package.json`, `next.config.ts`, `source.config.ts`, the root layout, `lib/geistdocs`, `proxy.ts`, and all imports from `@vercel/geistdocs/components` or `@vercel/geistdocs/assets`. Upgrade the dependencies, replace removed generic component imports with Geistcn, keep Geistdocs-specific components and route adapters package-backed, and verify every public surface. Do not copy package internals into the app.
20
+
21
+ ## 1. Upgrade dependencies
22
+
23
+ ```bash title="Terminal"
24
+ pnpm add --save-exact @vercel/geistdocs@2 @vercel/geistcn@1.0.3 @vercel/geistcn-assets@2.0.1 next@16.3.3 react@19.2.3 react-dom@19.2.3
25
+ ```
26
+
27
+ Geistdocs requires Node.js 20.9 or later. If the app directly uses Ask AI dependencies, use AI SDK v6 and `@ai-sdk/react` v3. Migrate unrelated AI features separately instead of forking Geistdocs chat code.
28
+
29
+ ## 2. Replace removed imports
30
+
31
+ | Geistdocs 1.x import | Geistdocs 2.0 replacement |
32
+ | --- | --- |
33
+ | `badge`, `button`, `dialog`, `drawer`, `input`, `kbd`, `separator`, `sheet`, `spinner`, `textarea`, `theme-switcher`, or `tooltip` | Import the matching component from `@vercel/geistcn/components/<name>`. |
34
+ | `switch` | Use `@vercel/geistcn/components/toggle`. |
35
+ | `sonner` | Use `Toasts` and `useToasts` from `@vercel/geistcn/components/toasts`. |
36
+ | `theme-aware-image` | Use Geistcn `Image` with `srcLight` and `srcDark`. |
37
+ | `button-group`, `card`, or `input-group` | Choose a Geistcn component or keep an app-owned composition; there is no API-compatible replacement. |
38
+ | `@vercel/geistdocs/assets/icons` or `assets/icons/*` | `@vercel/geistcn-assets/icons` or `icons/*` |
39
+ | `@vercel/geistdocs/assets/logos` or `assets/logos/*` | `@vercel/geistcn-assets/logos` or `logos/*` |
40
+
41
+ Keep documentation-specific imports such as `callout`, `code-block`, `code-block-tabs`, `collapsible`, `command-prompt`, `copy-prompt`, `mermaid`, and `video` on `@vercel/geistdocs/components/*`.
42
+
43
+ Import the package stylesheet once and apply the Geist font classes at the root:
44
+
45
+ ```tsx title="app/[lang]/layout.tsx"
46
+ import "@vercel/geistdocs/styles.css";
47
+ import { geistFontClasses } from "@vercel/geistcn/core";
48
+
49
+ export default function RootLayout({ children }: LayoutProps<"/[lang]">) {
50
+ return (
51
+ <html className={geistFontClasses}>
52
+ <body>{children}</body>
53
+ </html>
54
+ );
55
+ }
56
+ ```
57
+
58
+ ## 3. Use the Next.js and source integrations
59
+
60
+ ```ts title="next.config.ts"
61
+ import { createGeistdocs } from "@vercel/geistdocs/next";
62
+ import type { NextConfig } from "next";
63
+
64
+ const config: NextConfig = {
65
+ modularizeImports: {
66
+ "@vercel/geistcn/components": {
67
+ skipDefaultConversion: true,
68
+ transform: "@vercel/geistcn/components/{{ kebabCase member }}",
69
+ },
70
+ "@vercel/geistcn/core": {
71
+ skipDefaultConversion: true,
72
+ transform: "@vercel/geistcn/core",
73
+ },
74
+ },
75
+ transpilePackages: [
76
+ "@vercel/geistcn",
77
+ "@vercel/geist-test-utils",
78
+ "@vercel/next-themes",
79
+ ],
80
+ cacheComponents: true,
81
+ partialPrefetching: true,
82
+ };
83
+
84
+ export default createGeistdocs()(config);
85
+ ```
86
+
87
+ In `source.config.ts`, import `defineGeistdocsSourceConfig`, `geistdocsFrontmatterSchema`, and `geistdocsMetaSchema` only from `@vercel/geistdocs/source-config`. Keep pages and route handlers as thin adapters around Geistdocs package APIs.
88
+
89
+ ## 4. Preserve routing invariants
90
+
91
+ - If Next.js uses `basePath`, set the same value in Geistdocs config.
92
+ - Keep `content.route`, source `baseUrl`, navigation hrefs, `getPageUrl`, search results, and proxy `markdownRoutes` app-local. Next.js adds the mount prefix once; Geistdocs adds it to public metadata, Markdown, discovery links, and citations.
93
+ - For versioned docs, use `createVersionedSources` and pass server-computed `collectVersionSwitchPaths` to the version selector so missing pages fall back to an existing ancestor.
94
+ - Keep version and router dimensions in static route segments when layouts and sidebar state should persist. Build router-specific, prefix-relative path sets separately from version paths.
95
+ - Keep product-specific navigation titles, badges, related links, and content transforms in the app.
96
+
97
+ ## 5. Verify the upgrade
98
+
99
+ - Run install, typecheck, tests, and a production build.
100
+ - Open representative HTML pages and their `.md` equivalents, including a not-found path.
101
+ - Test search, Ask AI citations, proxy rewrites, and agent-readable routes.
102
+ - Switch versions from pages that do and do not exist in the target version.
103
+ - Confirm links do not trigger broad post-load prefetching and Ask AI is not eagerly loaded.
104
+ - Recheck LCP, CLS, accessibility, and post-render network and CPU activity.
105
+
106
+ For a first migration from Fumadocs or a custom docs site, follow the [full migration guide](/docs/migration).
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: Migration guide
2
+ title: Migrate to Geistdocs
3
3
  description: Migrate a Fumadocs or custom Geist docs site to package-backed Geistdocs
4
4
  type: guide
5
5
  summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
@@ -14,10 +14,13 @@ related:
14
14
  - /docs/agent-readiness
15
15
  ---
16
16
 
17
- # Migration guide
17
+ # Migrate to Geistdocs
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
+ > Note:
22
+ Follow the concise [1.x → 2.0 guide](/docs/migration-2) instead. This page is for adopting Geistdocs from Fumadocs or a custom documentation site.
23
+
21
24
  Help me migrate this existing docs site to package-backed Geistdocs. Inspect `source.config.ts`, `lib/geistdocs/source.ts`, app route files, `proxy.ts` or `middleware.ts`, `public/llms.txt`, Open Graph routes, Tailwind CSS setup, `package.json` AI SDK dependencies, and environment variables. Then produce a step-by-step migration plan using `@vercel/geistdocs` package APIs without copying package internals.
22
25
 
23
26
  ## Before you migrate
package/docs/sitemap.md CHANGED
@@ -6,8 +6,9 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
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
8
  - [Environment Variables](pages/env.md) | URL: /docs/env | Type: reference | Summary: Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
9
- - [Deploy to Vercel](pages/deployment.md) | URL: /docs/deployment | Type: guide | Summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
10
- - [Migration guide](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.
9
+ - [Deploy to Vercel](pages/deployment.md) | URL: /docs/deployment | Type: guide | Summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
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
+ - [Migrate from Geistdocs 1.x to 2.0](pages/migration-2.md) | URL: /docs/migration-2 | Type: guide | Summary: A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.
11
12
  - [Configuration](pages/configuration.md) | URL: /docs/configuration | Type: reference | Summary: Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
12
13
  - [Syntax](pages/syntax.md) | URL: /docs/syntax | Type: reference | Summary: Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
13
14
  - [Geistdocs Provider](pages/provider.md) | URL: /docs/provider | Type: reference | Summary: The root provider component that wraps your application to handle toast notifications, search, and analytics.
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": "1.25.1-canary.4e75e60",
4
+ "version": "1.25.1-canary.6261418",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -192,10 +192,9 @@
192
192
  "@clack/prompts": "^0.11.0",
193
193
  "@orama/tokenizers": "^3.1.16",
194
194
  "@streamdown/cjk": "^1.0.1",
195
- "@streamdown/code": "^1.0.1",
196
195
  "@vercel/agent-readability": "^0.7.0",
197
- "@vercel/geistcn": "1.0.3",
198
- "@vercel/geistcn-assets": "2.0.1",
196
+ "@vercel/geistcn": "1.0.4",
197
+ "@vercel/geistcn-assets": "2.1.0",
199
198
  "@vercel/oidc": "^3.4.1",
200
199
  "ai": "^6.0.132",
201
200
  "class-variance-authority": "^0.7.1",
@@ -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 your Geistdocs site to Vercel from the dashboard with the correct project settings.
5
+ summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
6
6
  prerequisites:
7
7
  - /docs/getting-started
8
8
  - /docs/env
@@ -10,10 +10,10 @@ related:
10
10
  - /docs/configuration
11
11
  ---
12
12
 
13
- Deploy a Geistdocs site to Vercel as a Next.js app. Make sure your package dependency, environment variables, and production URL are configured before shipping.
13
+ Deploy a Geistdocs site to Vercel as a Next.js app. Configure private package access, environment variables, and the production URL before shipping.
14
14
 
15
- <CopyPrompt text="Help me deploy this Geistdocs project to Vercel. Check the package scripts, required environment variables, and Vercel project settings, then give me a deploy checklist for production.">
16
- Help me deploy this Geistdocs project to Vercel. Check the package scripts, required environment variables, and Vercel project settings, then give me a deploy checklist for production.
15
+ <CopyPrompt text="Help me deploy this Geistdocs 2.0 project to Vercel. Verify private npm access for its Geistcn dependencies, then review the package scripts, environment variables, GitHub Actions authentication, and Vercel project settings.">
16
+ Help me deploy this Geistdocs 2.0 project to Vercel. Verify private npm access for its Geistcn dependencies, then review the package scripts, environment variables, GitHub Actions authentication, and Vercel project settings.
17
17
  </CopyPrompt>
18
18
 
19
19
  ## Prerequisites
@@ -24,6 +24,31 @@ Before deploying, you need:
24
24
  - A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
25
25
  - Your Vercel account connected to your GitHub account
26
26
  - Environment variables ready (see [Environment Variables](/docs/env))
27
+ - Access to the restricted `@vercel` npm packages
28
+
29
+ ## Configure private package access
30
+
31
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Package installation fails without npm authentication.
32
+
33
+ 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 required environments. Do not copy the shared token into the repository or project documentation.
34
+
35
+ For GitHub Actions, ask `#help-it` to allow the repository to use the `NPM_TOKEN` organization secret, then pass it to the install step:
36
+
37
+ ```yaml title=".github/workflows/check.yml"
38
+ - uses: pnpm/action-setup@v4
39
+
40
+ - uses: actions/setup-node@v4
41
+ with:
42
+ node-version: 20
43
+ cache: pnpm
44
+ registry-url: https://registry.npmjs.org
45
+
46
+ - run: pnpm install
47
+ env:
48
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
49
+ ```
50
+
51
+ Read [How do I use private dependencies with Vercel?](https://vercel.com/kb/guide/using-private-dependencies-with-vercel) for the platform authentication behavior.
27
52
 
28
53
  ## Deploy to Vercel
29
54
 
@@ -33,9 +58,9 @@ To deploy from the Vercel dashboard:
33
58
  2. Select your Geistdocs repository
34
59
  3. Configure your project settings:
35
60
  - **Framework Preset**: Next.js (automatically detected)
36
- - **Build Command**: `pnpm build` or `npm run build`
61
+ - **Build Command**: `pnpm build`
37
62
  - **Output Directory**: `.next` (default)
38
- - **Install Command**: `pnpm install` or `npm install`
63
+ - **Install Command**: `pnpm install`
39
64
  4. Add your environment variables (see [Environment Variables](/docs/env))
40
65
  5. Click "Deploy"
41
66
 
@@ -10,41 +10,49 @@ related:
10
10
  - /docs/deployment
11
11
  ---
12
12
 
13
- 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.
13
+ Create a new Geistdocs 2.0 site with the package CLI, then customize its identity, content, and navigation. If you already have a documentation site, use [Migrate to Geistdocs](/docs/migration) or [Migrate 1.x → 2.0](/docs/migration-2) instead.
14
14
 
15
- <CopyPrompt text="Create a Geistdocs project with pnpm dlx @vercel/geistdocs init --name my-docs. Then open my-docs, run pnpm dev, and explain which files I should edit first: geistdocs.tsx, content/docs, content/docs/meta.json, and components/geistdocs/mdx-components.tsx.">
16
- Create a Geistdocs project with `pnpm dlx @vercel/geistdocs init --name my-docs`. Then open `my-docs`, run `pnpm dev`, and explain which files I should edit first: `geistdocs.tsx`, `content/docs`, `content/docs/meta.json`, and `components/geistdocs/mdx-components.tsx`.
15
+ <CopyPrompt text="Create a new Geistdocs project with pnpm dlx @vercel/geistdocs@latest init --name my-docs. Confirm Node.js 20.9 or later, pnpm, Git, and npm access to the @vercel scope are available first. Then run pnpm dev and help me customize geistdocs.tsx, content/docs/index.mdx, and content/docs/meta.json. Keep the generated route, source, Geistcn, and Next.js integrations package-backed.">
16
+ Create a new Geistdocs project with `pnpm dlx @vercel/geistdocs@latest init --name my-docs`. Confirm the prerequisites, run `pnpm dev`, and help me customize `geistdocs.tsx`, `content/docs/index.mdx`, and `content/docs/meta.json`. Keep the generated integrations package-backed.
17
17
  </CopyPrompt>
18
18
 
19
19
  ## Prerequisites
20
20
 
21
21
  Before you begin, install:
22
22
 
23
- - Node.js 18 or later
24
- - pnpm, npm, or another package manager
23
+ - Node.js 20.9 or later
24
+ - pnpm
25
25
  - Git
26
26
 
27
- ## Create a project
27
+ The CLI always uses pnpm to install the generated project's dependencies.
28
28
 
29
- Run the Geistdocs CLI from an empty parent folder:
29
+ ## Authenticate package access
30
30
 
31
- ```bash title="Terminal"
32
- pnpm dlx @vercel/geistdocs init --name my-docs
31
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Configure your user-level `~/.npmrc` before running the CLI:
32
+
33
+ ```ini title="~/.npmrc"
34
+ @vercel:registry=https://registry.npmjs.org/
35
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
36
+ always-auth=true
33
37
  ```
34
38
 
35
- You can also use npm:
39
+ Set `NPM_TOKEN` from an approved internal source. Never put the token value in `.npmrc`, an `.env` file, shell history, or Git. See [Deploy to Vercel](/docs/deployment#configure-private-package-access) for automated installs.
40
+
41
+ ## Create a project
42
+
43
+ Run the Geistdocs CLI from an empty parent folder:
36
44
 
37
45
  ```bash title="Terminal"
38
- npx @vercel/geistdocs init --name my-docs
46
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
39
47
  ```
40
48
 
41
49
  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.
42
50
 
43
51
  ## Understand generated dependencies
44
52
 
45
- 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.
53
+ Generated projects pin the resolved `@vercel/geistdocs` version and include its matching Geistcn dependencies, AI SDK v6, and `@ai-sdk/react` v3. The template already configures styles, fonts, Cache Components, Partial Prefetching, source adapters, search, Ask AI, and agent-readable routes.
46
54
 
47
- 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.
55
+ Keep those integrations package-backed. Update Geistdocs instead of copying package internals into the app.
48
56
 
49
57
  ## Start the development server
50
58
 
@@ -57,6 +65,14 @@ pnpm dev
57
65
 
58
66
  Open `http://localhost:3000` in your browser.
59
67
 
68
+ Start with these files:
69
+
70
+ - `geistdocs.tsx` for the site title, logo, navigation, repository, and AI prompt.
71
+ - `content/docs/index.mdx` for the documentation overview.
72
+ - `content/docs/meta.json` for sidebar order and groups.
73
+
74
+ Only customize `components/geistdocs/*`, `lib/geistdocs/*`, or route adapters when the generated defaults do not fit your site.
75
+
60
76
  ## Edit your first page
61
77
 
62
78
  Docs live in `content/docs`. Edit the overview page:
@@ -114,3 +130,13 @@ pnpm exec geistdocs update
114
130
  ```
115
131
 
116
132
  Review and test dependency changes before committing.
133
+
134
+ ## Verify and deploy
135
+
136
+ Run a production build before publishing:
137
+
138
+ ```bash title="Terminal"
139
+ pnpm build
140
+ ```
141
+
142
+ Then follow [Deploy to Vercel](/docs/deployment), including private package access and environment-variable setup.
@@ -197,7 +197,7 @@ Geistdocs applies a color for each method:
197
197
  | `PUT`, `PATCH` | Amber |
198
198
  | `DEL`, `DELETE` | Red |
199
199
 
200
- Method matching is case-sensitive, so use uppercase labels. `DEL` and `DELETE` render the same red badge, so prefer `DEL` when you want a narrower badge. Any other label, such as `Beta`, keeps the default blue badge. Badge colors adapt to light and dark themes automatically.
200
+ Method matching is case-sensitive, so use uppercase labels. `DEL` and `DELETE` render the same red badge, so prefer `DEL` when you want a narrower badge. `New` renders as a low-contrast blue badge; other labels, such as `Beta`, use the default neutral badge. Badge colors adapt to light and dark themes automatically.
201
201
 
202
202
  ## Add links to the navigation
203
203
 
@@ -9,6 +9,7 @@
9
9
  "env",
10
10
  "deployment",
11
11
  "migration",
12
+ "migration-2",
12
13
  "configuration",
13
14
  "---Internals---",
14
15
  "syntax",
@@ -0,0 +1,106 @@
1
+ ---
2
+ title: Migrate from Geistdocs 1.x to 2.0
3
+ navTitle: Migrate 1.x → 2.0
4
+ badge: New
5
+ description: Upgrade imports, dependencies, and routing without copying Geistdocs internals
6
+ type: guide
7
+ summary: A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.
8
+ related:
9
+ - /docs/migration
10
+ - /docs/configuration
11
+ - /docs/versioned-docs
12
+ - /docs/proxy
13
+ ---
14
+
15
+ Use this guide only for a site already running Geistdocs 1.x. Geistdocs 2.0 moves shared UI primitives and assets to Geistcn; its package-backed page, source, search, chat, proxy, and agent-readable route APIs remain the preferred integration.
16
+
17
+ <CopyPrompt text="Upgrade this Geistdocs site from 1.x to 2.0. Inspect package.json, next.config.ts, source.config.ts, the root layout, lib/geistdocs, proxy.ts, and all imports from @vercel/geistdocs/components or @vercel/geistdocs/assets. Upgrade the dependencies, replace removed generic component imports with @vercel/geistcn/components/*, replace icon and logo imports with @vercel/geistcn-assets, keep Geistdocs-specific components and all route adapters package-backed, enable cacheComponents and partialPrefetching, apply geistFontClasses once, and preserve app-local paths when basePath is configured. If the site has versions, use createVersionedSources and pass collectVersionSwitchPaths to the version selector. Run install, typecheck, and build, then verify HTML, Markdown, search, Ask AI, and version fallbacks. Do not copy package internals into the app.">
18
+ Upgrade this Geistdocs site from 1.x to 2.0. Inspect `package.json`, `next.config.ts`, `source.config.ts`, the root layout, `lib/geistdocs`, `proxy.ts`, and all imports from `@vercel/geistdocs/components` or `@vercel/geistdocs/assets`. Upgrade the dependencies, replace removed generic component imports with Geistcn, keep Geistdocs-specific components and route adapters package-backed, and verify every public surface. Do not copy package internals into the app.
19
+ </CopyPrompt>
20
+
21
+ ## 1. Upgrade dependencies
22
+
23
+ ```bash title="Terminal"
24
+ pnpm add --save-exact @vercel/geistdocs@2 @vercel/geistcn@1.0.3 @vercel/geistcn-assets@2.0.1 next@16.3.3 react@19.2.3 react-dom@19.2.3
25
+ ```
26
+
27
+ Geistdocs requires Node.js 20.9 or later. If the app directly uses Ask AI dependencies, use AI SDK v6 and `@ai-sdk/react` v3. Migrate unrelated AI features separately instead of forking Geistdocs chat code.
28
+
29
+ ## 2. Replace removed imports
30
+
31
+ | Geistdocs 1.x import | Geistdocs 2.0 replacement |
32
+ | --- | --- |
33
+ | `badge`, `button`, `dialog`, `drawer`, `input`, `kbd`, `separator`, `sheet`, `spinner`, `textarea`, `theme-switcher`, or `tooltip` | Import the matching component from `@vercel/geistcn/components/<name>`. |
34
+ | `switch` | Use `@vercel/geistcn/components/toggle`. |
35
+ | `sonner` | Use `Toasts` and `useToasts` from `@vercel/geistcn/components/toasts`. |
36
+ | `theme-aware-image` | Use Geistcn `Image` with `srcLight` and `srcDark`. |
37
+ | `button-group`, `card`, or `input-group` | Choose a Geistcn component or keep an app-owned composition; there is no API-compatible replacement. |
38
+ | `@vercel/geistdocs/assets/icons` or `assets/icons/*` | `@vercel/geistcn-assets/icons` or `icons/*` |
39
+ | `@vercel/geistdocs/assets/logos` or `assets/logos/*` | `@vercel/geistcn-assets/logos` or `logos/*` |
40
+
41
+ Keep documentation-specific imports such as `callout`, `code-block`, `code-block-tabs`, `collapsible`, `command-prompt`, `copy-prompt`, `mermaid`, and `video` on `@vercel/geistdocs/components/*`.
42
+
43
+ Import the package stylesheet once and apply the Geist font classes at the root:
44
+
45
+ ```tsx title="app/[lang]/layout.tsx"
46
+ import "@vercel/geistdocs/styles.css";
47
+ import { geistFontClasses } from "@vercel/geistcn/core";
48
+
49
+ export default function RootLayout({ children }: LayoutProps<"/[lang]">) {
50
+ return (
51
+ <html className={geistFontClasses}>
52
+ <body>{children}</body>
53
+ </html>
54
+ );
55
+ }
56
+ ```
57
+
58
+ ## 3. Use the Next.js and source integrations
59
+
60
+ ```ts title="next.config.ts"
61
+ import { createGeistdocs } from "@vercel/geistdocs/next";
62
+ import type { NextConfig } from "next";
63
+
64
+ const config: NextConfig = {
65
+ modularizeImports: {
66
+ "@vercel/geistcn/components": {
67
+ skipDefaultConversion: true,
68
+ transform: "@vercel/geistcn/components/{{ kebabCase member }}",
69
+ },
70
+ "@vercel/geistcn/core": {
71
+ skipDefaultConversion: true,
72
+ transform: "@vercel/geistcn/core",
73
+ },
74
+ },
75
+ transpilePackages: [
76
+ "@vercel/geistcn",
77
+ "@vercel/geist-test-utils",
78
+ "@vercel/next-themes",
79
+ ],
80
+ cacheComponents: true,
81
+ partialPrefetching: true,
82
+ };
83
+
84
+ export default createGeistdocs()(config);
85
+ ```
86
+
87
+ In `source.config.ts`, import `defineGeistdocsSourceConfig`, `geistdocsFrontmatterSchema`, and `geistdocsMetaSchema` only from `@vercel/geistdocs/source-config`. Keep pages and route handlers as thin adapters around Geistdocs package APIs.
88
+
89
+ ## 4. Preserve routing invariants
90
+
91
+ - If Next.js uses `basePath`, set the same value in Geistdocs config.
92
+ - Keep `content.route`, source `baseUrl`, navigation hrefs, `getPageUrl`, search results, and proxy `markdownRoutes` app-local. Next.js adds the mount prefix once; Geistdocs adds it to public metadata, Markdown, discovery links, and citations.
93
+ - For versioned docs, use `createVersionedSources` and pass server-computed `collectVersionSwitchPaths` to the version selector so missing pages fall back to an existing ancestor.
94
+ - Keep version and router dimensions in static route segments when layouts and sidebar state should persist. Build router-specific, prefix-relative path sets separately from version paths.
95
+ - Keep product-specific navigation titles, badges, related links, and content transforms in the app.
96
+
97
+ ## 5. Verify the upgrade
98
+
99
+ - Run install, typecheck, tests, and a production build.
100
+ - Open representative HTML pages and their `.md` equivalents, including a not-found path.
101
+ - Test search, Ask AI citations, proxy rewrites, and agent-readable routes.
102
+ - Switch versions from pages that do and do not exist in the target version.
103
+ - Confirm links do not trigger broad post-load prefetching and Ask AI is not eagerly loaded.
104
+ - Recheck LCP, CLS, accessibility, and post-render network and CPU activity.
105
+
106
+ For a first migration from Fumadocs or a custom docs site, follow the [full migration guide](/docs/migration).
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: Migration guide
2
+ title: Migrate to Geistdocs
3
3
  description: Migrate a Fumadocs or custom Geist docs site to package-backed Geistdocs
4
4
  type: guide
5
5
  summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
@@ -14,6 +14,10 @@ related:
14
14
 
15
15
  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.
16
16
 
17
+ <Callout title="Already use Geistdocs 1.x?">
18
+ Follow the concise [1.x → 2.0 guide](/docs/migration-2) instead. This page is for adopting Geistdocs from Fumadocs or a custom documentation site.
19
+ </Callout>
20
+
17
21
  <CopyPrompt text="Help me migrate this existing docs site to package-backed Geistdocs. Inspect source.config.ts, lib/geistdocs/source.ts, app route files, proxy.ts or middleware.ts, public/llms.txt, Open Graph routes, Tailwind CSS setup, package.json AI SDK dependencies, and environment variables. Then produce a step-by-step migration plan using @vercel/geistdocs package APIs without copying package internals.">
18
22
  Help me migrate this existing docs site to package-backed Geistdocs. Inspect `source.config.ts`, `lib/geistdocs/source.ts`, app route files, `proxy.ts` or `middleware.ts`, `public/llms.txt`, Open Graph routes, Tailwind CSS setup, `package.json` AI SDK dependencies, and environment variables. Then produce a step-by-step migration plan using `@vercel/geistdocs` package APIs without copying package internals.
19
23
  </CopyPrompt>
@@ -17,9 +17,9 @@
17
17
  "@streamdown/code": "^1.0.1",
18
18
  "@vercel/agent-readability": "^0.7.0",
19
19
  "@vercel/analytics": "^1.6.1",
20
- "@vercel/geistcn": "1.0.3",
21
- "@vercel/geistcn-assets": "2.0.1",
22
- "@vercel/geistdocs": "1.25.1-canary.4e75e60",
20
+ "@vercel/geistcn": "1.0.4",
21
+ "@vercel/geistcn-assets": "2.1.0",
22
+ "@vercel/geistdocs": "1.25.1-canary.6261418",
23
23
  "@vercel/speed-insights": "^1.3.1",
24
24
  "ai": "^6.0.132",
25
25
  "class-variance-authority": "^0.7.1",
package/theme.css CHANGED
@@ -227,10 +227,6 @@ button:not(:disabled, [aria-disabled="true"]) {
227
227
  }
228
228
  }
229
229
 
230
- [data-geistdocs-command-modal] {
231
- box-shadow: var(--ds-shadow-modal);
232
- }
233
-
234
230
  [data-geistdocs-command-modal] .text-fd-muted-foreground {
235
231
  color: var(--ds-gray-900);
236
232
  }