@vercel/geistdocs 1.25.1-canary.984aaa9 → 1.25.1-canary.9c4de00

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 (112) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/components/callout.d.ts.map +1 -1
  3. package/dist/components/callout.js +2 -2
  4. package/dist/components/code-block-tabs.js +1 -1
  5. package/dist/components/code-block.d.ts.map +1 -1
  6. package/dist/components/code-block.js +1 -1
  7. package/dist/components/command-prompt.d.ts.map +1 -1
  8. package/dist/components/command-prompt.js +15 -22
  9. package/dist/components/copy-prompt.js +1 -1
  10. package/dist/controls.d.ts.map +1 -1
  11. package/dist/controls.js +3 -2
  12. package/dist/internal/chat/activity.d.ts +20 -0
  13. package/dist/internal/chat/activity.d.ts.map +1 -0
  14. package/dist/internal/chat/activity.js +43 -0
  15. package/dist/internal/chat/context.d.ts +2 -0
  16. package/dist/internal/chat/context.d.ts.map +1 -1
  17. package/dist/internal/chat/context.js +24 -3
  18. package/dist/internal/chat/dots-spinner.d.ts.map +1 -1
  19. package/dist/internal/chat/dots-spinner.js +15 -9
  20. package/dist/internal/chat/loading-skeleton.d.ts +7 -0
  21. package/dist/internal/chat/loading-skeleton.d.ts.map +1 -0
  22. package/dist/internal/chat/loading-skeleton.js +46 -0
  23. package/dist/internal/chat/message-metadata.d.ts.map +1 -1
  24. package/dist/internal/chat/message-metadata.js +15 -30
  25. package/dist/internal/chat/message-sources.d.ts +3 -0
  26. package/dist/internal/chat/message-sources.d.ts.map +1 -0
  27. package/dist/internal/chat/message-sources.js +23 -0
  28. package/dist/internal/chat/message.d.ts.map +1 -1
  29. package/dist/internal/chat/message.js +59 -5
  30. package/dist/internal/chat/shell.d.ts.map +1 -1
  31. package/dist/internal/chat/shell.js +17 -17
  32. package/dist/internal/chat/source-chunks.d.ts +9 -0
  33. package/dist/internal/chat/source-chunks.d.ts.map +1 -0
  34. package/dist/internal/chat/source-chunks.js +7 -0
  35. package/dist/internal/chat/sources.d.ts +1 -1
  36. package/dist/internal/chat/sources.d.ts.map +1 -1
  37. package/dist/internal/chat/sources.js +7 -1
  38. package/dist/internal/link-href.d.ts +13 -0
  39. package/dist/internal/link-href.d.ts.map +1 -0
  40. package/dist/internal/link-href.js +51 -0
  41. package/dist/internal/mousedown-navigation-utils.d.ts +5 -0
  42. package/dist/internal/mousedown-navigation-utils.d.ts.map +1 -0
  43. package/dist/internal/mousedown-navigation-utils.js +95 -0
  44. package/dist/internal/mousedown-navigation.d.ts +10 -0
  45. package/dist/internal/mousedown-navigation.d.ts.map +1 -0
  46. package/dist/internal/mousedown-navigation.js +42 -0
  47. package/dist/internal/navbar/desktop-menu.js +1 -1
  48. package/dist/internal/navbar/mobile-menu.d.ts.map +1 -1
  49. package/dist/internal/navbar/mobile-menu.js +8 -13
  50. package/dist/internal/navbar/navbar-shell.d.ts.map +1 -1
  51. package/dist/internal/navbar/navbar-shell.js +2 -1
  52. package/dist/internal/page-actions-client.d.ts.map +1 -1
  53. package/dist/internal/page-actions-client.js +6 -23
  54. package/dist/internal/provider-client.d.ts.map +1 -1
  55. package/dist/internal/provider-client.js +29 -5
  56. package/dist/internal/search.js +1 -1
  57. package/dist/internal/sidebar-responsive.d.ts +0 -1
  58. package/dist/internal/sidebar-responsive.d.ts.map +1 -1
  59. package/dist/internal/sidebar-responsive.js +0 -9
  60. package/dist/internal/sidebar-tree.d.ts.map +1 -1
  61. package/dist/internal/sidebar-tree.js +6 -1
  62. package/dist/internal/sidebar.d.ts.map +1 -1
  63. package/dist/internal/sidebar.js +65 -39
  64. package/dist/internal/toc-items.d.ts.map +1 -1
  65. package/dist/internal/toc-items.js +16 -6
  66. package/dist/internal/ui/navigation-menu.js +2 -2
  67. package/dist/internal/use-mobile.d.ts.map +1 -1
  68. package/dist/internal/use-mobile.js +2 -12
  69. package/dist/layout.d.ts +1 -0
  70. package/dist/layout.d.ts.map +1 -1
  71. package/dist/layout.js +2 -0
  72. package/dist/mdx.d.ts.map +1 -1
  73. package/dist/mdx.js +2 -4
  74. package/dist/pages/docs.d.ts.map +1 -1
  75. package/dist/pages/docs.js +17 -9
  76. package/dist/routes/chat.d.ts +1 -1
  77. package/dist/routes/chat.d.ts.map +1 -1
  78. package/dist/routes/chat.js +31 -14
  79. package/dist/routes/llms.d.ts +1 -1
  80. package/dist/routes/llms.d.ts.map +1 -1
  81. package/dist/routes/llms.js +12 -2
  82. package/dist/source.d.ts +6 -1
  83. package/dist/source.d.ts.map +1 -1
  84. package/dist/source.js +1 -0
  85. package/dist/versions.js +2 -2
  86. package/docs/agents.md +4 -3
  87. package/docs/llms.txt +231 -29
  88. package/docs/manifest.json +12 -3
  89. package/docs/pages/ask-ai.md +2 -2
  90. package/docs/pages/deployment.md +30 -5
  91. package/docs/pages/getting-started.md +38 -12
  92. package/docs/pages/guides/nested-navigation.md +1 -1
  93. package/docs/pages/md.md +1 -1
  94. package/docs/pages/migration-2.md +106 -0
  95. package/docs/pages/migration.md +5 -2
  96. package/docs/pages/syntax.md +40 -3
  97. package/docs/sitemap.md +3 -2
  98. package/package.json +5 -5
  99. package/template/app/[lang]/layout.tsx +4 -0
  100. package/template/components/ui/button.tsx +1 -1
  101. package/template/content/docs/ask-ai.cn.mdx +2 -2
  102. package/template/content/docs/ask-ai.mdx +2 -2
  103. package/template/content/docs/deployment.mdx +31 -6
  104. package/template/content/docs/getting-started.mdx +39 -13
  105. package/template/content/docs/guides/nested-navigation.mdx +1 -1
  106. package/template/content/docs/md.mdx +1 -1
  107. package/template/content/docs/meta.json +1 -0
  108. package/template/content/docs/migration-2.mdx +106 -0
  109. package/template/content/docs/migration.mdx +5 -1
  110. package/template/content/docs/syntax.mdx +41 -3
  111. package/template/package.json +4 -4
  112. package/theme.css +0 -4
package/docs/llms.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Documentation
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 1.25.1-canary.984aaa9.
3
+ These docs are bundled with `@vercel/geistdocs` 1.25.1-canary.9c4de00.
4
4
  They describe how to build package-backed Geistdocs sites and how to use the package APIs from generated project adapters.
5
5
 
6
6
  ## Documentation Index
@@ -8,8 +8,9 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
8
8
  - [Overview](pages/index.md): Geistdocs is a packaged documentation system for creating Next.js and Fumadocs sites with shared runtime features.
9
9
  - [Getting Started](pages/getting-started.md): Create a Geistdocs project, run it locally, and edit your first documentation page.
10
10
  - [Environment Variables](pages/env.md): Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
11
- - [Deploy to Vercel](pages/deployment.md): Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
12
- - [Migration guide](pages/migration.md): Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
11
+ - [Deploy to Vercel](pages/deployment.md): Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
12
+ - [Migrate to Geistdocs](pages/migration.md): Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
13
+ - [Migrate from Geistdocs 1.x to 2.0](pages/migration-2.md): A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.
13
14
  - [Configuration](pages/configuration.md): Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
14
15
  - [Syntax](pages/syntax.md): Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
15
16
  - [Geistdocs Provider](pages/provider.md): The root provider component that wraps your application to handle toast notifications, search, and analytics.
@@ -148,39 +149,47 @@ related:
148
149
 
149
150
  # Getting Started
150
151
 
151
- 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.
152
+ 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.
152
153
 
153
- 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`.
154
+ 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.
154
155
 
155
156
  ## Prerequisites
156
157
 
157
158
  Before you begin, install:
158
159
 
159
- - Node.js 18 or later
160
- - pnpm, npm, or another package manager
160
+ - Node.js 20.9 or later
161
+ - pnpm
161
162
  - Git
162
163
 
163
- ## Create a project
164
+ The CLI always uses pnpm to install the generated project's dependencies.
164
165
 
165
- Run the Geistdocs CLI from an empty parent folder:
166
+ ## Authenticate package access
166
167
 
167
- ```bash title="Terminal"
168
- pnpm dlx @vercel/geistdocs init --name my-docs
168
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Configure your user-level `~/.npmrc` before running the CLI:
169
+
170
+ ```ini title="~/.npmrc"
171
+ @vercel:registry=https://registry.npmjs.org/
172
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
173
+ always-auth=true
169
174
  ```
170
175
 
171
- You can also use npm:
176
+ 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.
177
+
178
+ ## Create a project
179
+
180
+ Run the Geistdocs CLI from an empty parent folder:
172
181
 
173
182
  ```bash title="Terminal"
174
- npx @vercel/geistdocs init --name my-docs
183
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
175
184
  ```
176
185
 
177
186
  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.
178
187
 
179
188
  ## Understand generated dependencies
180
189
 
181
- 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.
190
+ 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.
182
191
 
183
- 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.
192
+ Keep those integrations package-backed. Update Geistdocs instead of copying package internals into the app.
184
193
 
185
194
  ## Start the development server
186
195
 
@@ -193,6 +202,14 @@ pnpm dev
193
202
 
194
203
  Open `http://localhost:3000` in your browser.
195
204
 
205
+ Start with these files:
206
+
207
+ - `geistdocs.tsx` for the site title, logo, navigation, repository, and AI prompt.
208
+ - `content/docs/index.mdx` for the documentation overview.
209
+ - `content/docs/meta.json` for sidebar order and groups.
210
+
211
+ Only customize `components/geistdocs/*`, `lib/geistdocs/*`, or route adapters when the generated defaults do not fit your site.
212
+
196
213
  ## Edit your first page
197
214
 
198
215
  Docs live in `content/docs`. Edit the overview page:
@@ -251,6 +268,16 @@ pnpm exec geistdocs update
251
268
 
252
269
  Review and test dependency changes before committing.
253
270
 
271
+ ## Verify and deploy
272
+
273
+ Run a production build before publishing:
274
+
275
+ ```bash title="Terminal"
276
+ pnpm build
277
+ ```
278
+
279
+ Then follow [Deploy to Vercel](/docs/deployment), including private package access and environment-variable setup.
280
+
254
281
 
255
282
  ---
256
283
 
@@ -324,7 +351,7 @@ Set this variable explicitly when deploying outside Vercel. Use a hostname such
324
351
  title: Deploy to Vercel
325
352
  description: Learn how to deploy your Geistdocs site to Vercel
326
353
  type: guide
327
- summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
354
+ summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
328
355
  url: /docs/deployment
329
356
  source: apps/template/content/docs/deployment.mdx
330
357
  prerequisites:
@@ -336,9 +363,9 @@ related:
336
363
 
337
364
  # Deploy to Vercel
338
365
 
339
- 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.
366
+ Deploy a Geistdocs site to Vercel as a Next.js app. Configure private package access, environment variables, and the production URL before shipping.
340
367
 
341
- 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.
368
+ 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.
342
369
 
343
370
  ## Prerequisites
344
371
 
@@ -348,6 +375,31 @@ Before deploying, you need:
348
375
  - A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
349
376
  - Your Vercel account connected to your GitHub account
350
377
  - Environment variables ready (see [Environment Variables](/docs/env))
378
+ - Access to the restricted `@vercel` npm packages
379
+
380
+ ## Configure private package access
381
+
382
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Package installation fails without npm authentication.
383
+
384
+ 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.
385
+
386
+ For GitHub Actions, ask `#help-it` to allow the repository to use the `NPM_TOKEN` organization secret, then pass it to the install step:
387
+
388
+ ```yaml title=".github/workflows/check.yml"
389
+ - uses: pnpm/action-setup@v4
390
+
391
+ - uses: actions/setup-node@v4
392
+ with:
393
+ node-version: 20
394
+ cache: pnpm
395
+ registry-url: https://registry.npmjs.org
396
+
397
+ - run: pnpm install
398
+ env:
399
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
400
+ ```
401
+
402
+ Read [How do I use private dependencies with Vercel?](https://vercel.com/kb/guide/using-private-dependencies-with-vercel) for the platform authentication behavior.
351
403
 
352
404
  ## Deploy to Vercel
353
405
 
@@ -357,9 +409,9 @@ To deploy from the Vercel dashboard:
357
409
  2. Select your Geistdocs repository
358
410
  3. Configure your project settings:
359
411
  - **Framework Preset**: Next.js (automatically detected)
360
- - **Build Command**: `pnpm build` or `npm run build`
412
+ - **Build Command**: `pnpm build`
361
413
  - **Output Directory**: `.next` (default)
362
- - **Install Command**: `pnpm install` or `npm install`
414
+ - **Install Command**: `pnpm install`
363
415
  4. Add your environment variables (see [Environment Variables](/docs/env))
364
416
  5. Click "Deploy"
365
417
 
@@ -378,7 +430,7 @@ The Geistdocs site does not need Vertex credentials. The platform proxy authenti
378
430
  ---
379
431
 
380
432
  ---
381
- title: Migration guide
433
+ title: Migrate to Geistdocs
382
434
  description: Migrate a Fumadocs or custom Geist docs site to package-backed Geistdocs
383
435
  type: guide
384
436
  summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
@@ -393,10 +445,13 @@ related:
393
445
  - /docs/agent-readiness
394
446
  ---
395
447
 
396
- # Migration guide
448
+ # Migrate to Geistdocs
397
449
 
398
450
  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.
399
451
 
452
+ > Note:
453
+ 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.
454
+
400
455
  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.
401
456
 
402
457
  ## Before you migrate
@@ -804,6 +859,116 @@ Check these URLs locally:
804
859
  - Read [Agent readiness](/docs/agent-readiness) to configure `/agents.md` and `/.well-known/mcp.json` for AI agents.
805
860
 
806
861
 
862
+ ---
863
+
864
+ ---
865
+ title: Migrate from Geistdocs 1.x to 2.0
866
+ description: Upgrade imports, dependencies, and routing without copying Geistdocs internals
867
+ type: guide
868
+ summary: A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.
869
+ url: /docs/migration-2
870
+ source: apps/template/content/docs/migration-2.mdx
871
+ related:
872
+ - /docs/migration
873
+ - /docs/configuration
874
+ - /docs/versioned-docs
875
+ - /docs/proxy
876
+ ---
877
+
878
+ # Migrate from Geistdocs 1.x to 2.0
879
+
880
+ 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.
881
+
882
+ 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.
883
+
884
+ ## 1. Upgrade dependencies
885
+
886
+ ```bash title="Terminal"
887
+ 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
888
+ ```
889
+
890
+ 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.
891
+
892
+ ## 2. Replace removed imports
893
+
894
+ | Geistdocs 1.x import | Geistdocs 2.0 replacement |
895
+ | --- | --- |
896
+ | `badge`, `button`, `dialog`, `drawer`, `input`, `kbd`, `separator`, `sheet`, `spinner`, `textarea`, `theme-switcher`, or `tooltip` | Import the matching component from `@vercel/geistcn/components/<name>`. |
897
+ | `switch` | Use `@vercel/geistcn/components/toggle`. |
898
+ | `sonner` | Use `Toasts` and `useToasts` from `@vercel/geistcn/components/toasts`. |
899
+ | `theme-aware-image` | Use Geistcn `Image` with `srcLight` and `srcDark`. |
900
+ | `button-group`, `card`, or `input-group` | Choose a Geistcn component or keep an app-owned composition; there is no API-compatible replacement. |
901
+ | `@vercel/geistdocs/assets/icons` or `assets/icons/*` | `@vercel/geistcn-assets/icons` or `icons/*` |
902
+ | `@vercel/geistdocs/assets/logos` or `assets/logos/*` | `@vercel/geistcn-assets/logos` or `logos/*` |
903
+
904
+ Keep documentation-specific imports such as `callout`, `code-block`, `code-block-tabs`, `collapsible`, `command-prompt`, `copy-prompt`, `mermaid`, and `video` on `@vercel/geistdocs/components/*`.
905
+
906
+ Import the package stylesheet once and apply the Geist font classes at the root:
907
+
908
+ ```tsx title="app/[lang]/layout.tsx"
909
+ import "@vercel/geistdocs/styles.css";
910
+ import { geistFontClasses } from "@vercel/geistcn/core";
911
+
912
+ export default function RootLayout({ children }: LayoutProps<"/[lang]">) {
913
+ return (
914
+ <html className={geistFontClasses}>
915
+ <body>{children}</body>
916
+ </html>
917
+ );
918
+ }
919
+ ```
920
+
921
+ ## 3. Use the Next.js and source integrations
922
+
923
+ ```ts title="next.config.ts"
924
+ import { createGeistdocs } from "@vercel/geistdocs/next";
925
+ import type { NextConfig } from "next";
926
+
927
+ const config: NextConfig = {
928
+ modularizeImports: {
929
+ "@vercel/geistcn/components": {
930
+ skipDefaultConversion: true,
931
+ transform: "@vercel/geistcn/components/{{ kebabCase member }}",
932
+ },
933
+ "@vercel/geistcn/core": {
934
+ skipDefaultConversion: true,
935
+ transform: "@vercel/geistcn/core",
936
+ },
937
+ },
938
+ transpilePackages: [
939
+ "@vercel/geistcn",
940
+ "@vercel/geist-test-utils",
941
+ "@vercel/next-themes",
942
+ ],
943
+ cacheComponents: true,
944
+ partialPrefetching: true,
945
+ };
946
+
947
+ export default createGeistdocs()(config);
948
+ ```
949
+
950
+ 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.
951
+
952
+ ## 4. Preserve routing invariants
953
+
954
+ - If Next.js uses `basePath`, set the same value in Geistdocs config.
955
+ - 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.
956
+ - For versioned docs, use `createVersionedSources` and pass server-computed `collectVersionSwitchPaths` to the version selector so missing pages fall back to an existing ancestor.
957
+ - 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.
958
+ - Keep product-specific navigation titles, badges, related links, and content transforms in the app.
959
+
960
+ ## 5. Verify the upgrade
961
+
962
+ - Run install, typecheck, tests, and a production build.
963
+ - Open representative HTML pages and their `.md` equivalents, including a not-found path.
964
+ - Test search, Ask AI citations, proxy rewrites, and agent-readable routes.
965
+ - Switch versions from pages that do and do not exist in the target version.
966
+ - Confirm links do not trigger broad post-load prefetching and Ask AI is not eagerly loaded.
967
+ - Recheck LCP, CLS, accessibility, and post-render network and CPU activity.
968
+
969
+ For a first migration from Fumadocs or a custom docs site, follow the [full migration guide](/docs/migration).
970
+
971
+
807
972
  ---
808
973
 
809
974
  ---
@@ -1302,6 +1467,33 @@ Callouts can also contain a title and lists:
1302
1467
  package.json for tooling and ecosystem compatibility.
1303
1468
  - The `Pages Router` uses the React version from your `package.json`.
1304
1469
 
1470
+ Callouts support rich inline Markdown, including code, emphasis, and links:
1471
+
1472
+ ```mdx
1473
+ <Callout title="Good to know">
1474
+ Global styles can be imported into any layout, page, or component inside the
1475
+ `app` directory. However, since Next.js uses React's built-in support for
1476
+ stylesheets to integrate with Suspense, this currently does not remove
1477
+ stylesheets as you navigate between routes which can lead to conflicts. We
1478
+ recommend using global styles for _truly global_ CSS (like Tailwind's base
1479
+ styles), [Tailwind CSS](https://tailwindcss.com) for component styling, and
1480
+ [CSS Modules](https://nextjs.org/docs/app/getting-started/css#css-modules) for
1481
+ custom scoped CSS when needed.
1482
+ </Callout>
1483
+ ```
1484
+
1485
+ This renders as:
1486
+
1487
+ > Note:
1488
+ Global styles can be imported into any layout, page, or component inside the
1489
+ `app` directory. However, since Next.js uses React's built-in support for
1490
+ stylesheets to integrate with Suspense, this currently does not remove
1491
+ stylesheets as you navigate between routes which can lead to conflicts. We
1492
+ recommend using global styles for _truly global_ CSS (like Tailwind's base
1493
+ styles), [Tailwind CSS](https://tailwindcss.com) for component styling, and
1494
+ [CSS Modules](https://nextjs.org/docs/app/getting-started/css#css-modules) for
1495
+ custom scoped CSS when needed.
1496
+
1305
1497
  ### Copy Prompts
1306
1498
 
1307
1499
  Short prompts render in full without an expansion control:
@@ -1344,15 +1536,25 @@ Create links with `[text](url)`:
1344
1536
  - [External link](https://vercel.com)
1345
1537
  - [Internal link](/docs/getting-started)
1346
1538
 
1347
- Use an absolute `https://` or `http://` URL to mark a link as external. External
1348
- links open outside the docs site and display an arrow icon. Use a root-relative
1349
- path beginning with `/` for internal links:
1539
+ Use an absolute `https://` or `http://` URL for an external destination. Use a
1540
+ root-relative path beginning with `/` for an internal link. Both use the same
1541
+ visual styling:
1350
1542
 
1351
1543
  ```md
1352
1544
  [External link](https://vercel.com)
1353
1545
  [Internal link](/docs/getting-started)
1354
1546
  ```
1355
1547
 
1548
+ Links can also contain inline code:
1549
+
1550
+ ```md
1551
+ Run independent requests in parallel with [`Promise.all`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/all).
1552
+ ```
1553
+
1554
+ This renders as:
1555
+
1556
+ Run independent requests in parallel with [`Promise.all`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/all).
1557
+
1356
1558
  ### Images
1357
1559
 
1358
1560
  Add images with `![alt text](url)`:
@@ -2432,7 +2634,7 @@ The `.mdx` version returns:
2432
2634
 
2433
2635
  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`.
2434
2636
 
2435
- 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.
2637
+ 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.
2436
2638
 
2437
2639
  ## Use cases
2438
2640
 
@@ -2764,7 +2966,7 @@ In this mode, Geistdocs uses the local `search_docs` tool during the AI SDK `str
2764
2966
 
2765
2967
  #### Choose a model
2766
2968
 
2767
- Pass the `model` option to `createChatRoute` to control which model answers Ask AI requests. It accepts any AI SDK `LanguageModel`, including AI Gateway model strings, and defaults to `openai/gpt-4.1-mini`.
2969
+ Pass the `model` option to `createChatRoute` to control which model answers Ask AI requests. It accepts any AI SDK `LanguageModel`, including AI Gateway model strings, and defaults to `openai/gpt-5.6-sol`.
2768
2970
 
2769
2971
  ```ts title="app/api/chat/route.ts"
2770
2972
  import { createChatRoute } from "@vercel/geistdocs/routes/chat";
@@ -2873,7 +3075,7 @@ The chat interface adapts to different screen sizes:
2873
3075
 
2874
3076
  The environment variables `AI_GATEWAY_API_KEY` and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` must be set for the default AI Gateway mode. Set `GEISTDOCS_CHAT_PROXY_URL` to route Ask AI through a Vertex-backed proxy instead. You can read more in the [Environment Variables](/docs/env) section.
2875
3077
 
2876
- In default AI Gateway mode, Geistdocs uses `openai/gpt-4.1-mini` via the Vercel AI Gateway. In Vertex-backed proxy mode, the configured proxy controls the upstream model.
3078
+ In default AI Gateway mode, Geistdocs uses `openai/gpt-5.6-sol` via the Vercel AI Gateway. In Vertex-backed proxy mode, the configured proxy controls the upstream model.
2877
3079
 
2878
3080
  ## Suggested Prompts
2879
3081
 
@@ -3084,7 +3286,7 @@ Geistdocs applies a color for each method:
3084
3286
  | `PUT`, `PATCH` | Amber |
3085
3287
  | `DEL`, `DELETE` | Red |
3086
3288
 
3087
- 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.
3289
+ 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.
3088
3290
 
3089
3291
  ## Add links to the navigation
3090
3292
 
@@ -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 your Geistdocs site to Vercel from the dashboard with the correct project settings.",
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"
@@ -49,10 +49,19 @@
49
49
  "path": "pages/migration.md",
50
50
  "source": "apps/template/content/docs/migration.mdx",
51
51
  "summary": "Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.",
52
- "title": "Migration guide",
52
+ "title": "Migrate to Geistdocs",
53
53
  "type": "guide",
54
54
  "url": "/docs/migration"
55
55
  },
56
+ {
57
+ "description": "Upgrade imports, dependencies, and routing without copying Geistdocs internals",
58
+ "path": "pages/migration-2.md",
59
+ "source": "apps/template/content/docs/migration-2.mdx",
60
+ "summary": "A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.",
61
+ "title": "Migrate from Geistdocs 1.x to 2.0",
62
+ "type": "guide",
63
+ "url": "/docs/migration-2"
64
+ },
56
65
  {
57
66
  "description": "Configure a Geistdocs site through local adapter files and package APIs",
58
67
  "path": "pages/configuration.md",
@@ -199,5 +208,5 @@
199
208
  }
200
209
  ],
201
210
  "source": "apps/template/content/docs",
202
- "version": "1.25.1-canary.984aaa9"
211
+ "version": "1.25.1-canary.9c4de00"
203
212
  }
@@ -93,7 +93,7 @@ In this mode, Geistdocs uses the local `search_docs` tool during the AI SDK `str
93
93
 
94
94
  #### Choose a model
95
95
 
96
- Pass the `model` option to `createChatRoute` to control which model answers Ask AI requests. It accepts any AI SDK `LanguageModel`, including AI Gateway model strings, and defaults to `openai/gpt-4.1-mini`.
96
+ Pass the `model` option to `createChatRoute` to control which model answers Ask AI requests. It accepts any AI SDK `LanguageModel`, including AI Gateway model strings, and defaults to `openai/gpt-5.6-sol`.
97
97
 
98
98
  ```ts title="app/api/chat/route.ts"
99
99
  import { createChatRoute } from "@vercel/geistdocs/routes/chat";
@@ -202,7 +202,7 @@ The chat interface adapts to different screen sizes:
202
202
 
203
203
  The environment variables `AI_GATEWAY_API_KEY` and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` must be set for the default AI Gateway mode. Set `GEISTDOCS_CHAT_PROXY_URL` to route Ask AI through a Vertex-backed proxy instead. You can read more in the [Environment Variables](/docs/env) section.
204
204
 
205
- In default AI Gateway mode, Geistdocs uses `openai/gpt-4.1-mini` via the Vercel AI Gateway. In Vertex-backed proxy mode, the configured proxy controls the upstream model.
205
+ In default AI Gateway mode, Geistdocs uses `openai/gpt-5.6-sol` via the Vercel AI Gateway. In Vertex-backed proxy mode, the configured proxy controls the upstream model.
206
206
 
207
207
  ## Suggested Prompts
208
208
 
@@ -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
  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. Make sure your package dependency, environment variables, and production URL are configured before shipping.
17
+ Deploy a Geistdocs site to Vercel as a Next.js app. Configure private package access, environment variables, and the production URL before shipping.
18
18
 
19
- 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.
19
+ 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.
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 the restricted `@vercel` npm packages
30
+
31
+ ## Configure private package access
32
+
33
+ Geistdocs 2.0 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 required environments. Do not copy the shared token into the repository or project documentation.
36
+
37
+ For GitHub Actions, ask `#help-it` to allow the repository to use the `NPM_TOKEN` organization secret, then pass it to the install step:
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 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` or `npm run build`
63
+ - **Build Command**: `pnpm build`
39
64
  - **Output Directory**: `.next` (default)
40
- - **Install Command**: `pnpm install` or `npm 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
 
@@ -14,39 +14,47 @@ related:
14
14
 
15
15
  # Getting Started
16
16
 
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.
17
+ 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.
18
18
 
19
- 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`.
19
+ 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.
20
20
 
21
21
  ## Prerequisites
22
22
 
23
23
  Before you begin, install:
24
24
 
25
- - Node.js 18 or later
26
- - pnpm, npm, or another package manager
25
+ - Node.js 20.9 or later
26
+ - pnpm
27
27
  - Git
28
28
 
29
- ## Create a project
29
+ The CLI always uses pnpm to install the generated project's dependencies.
30
30
 
31
- Run the Geistdocs CLI from an empty parent folder:
31
+ ## Authenticate package access
32
32
 
33
- ```bash title="Terminal"
34
- pnpm dlx @vercel/geistdocs init --name my-docs
33
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Configure your user-level `~/.npmrc` before running the CLI:
34
+
35
+ ```ini title="~/.npmrc"
36
+ @vercel:registry=https://registry.npmjs.org/
37
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
38
+ always-auth=true
35
39
  ```
36
40
 
37
- You can also use npm:
41
+ 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.
42
+
43
+ ## Create a project
44
+
45
+ Run the Geistdocs CLI from an empty parent folder:
38
46
 
39
47
  ```bash title="Terminal"
40
- npx @vercel/geistdocs init --name my-docs
48
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
41
49
  ```
42
50
 
43
51
  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
52
 
45
53
  ## Understand generated dependencies
46
54
 
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.
55
+ 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.
48
56
 
49
- 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.
57
+ Keep those integrations package-backed. Update Geistdocs instead of copying package internals into the app.
50
58
 
51
59
  ## Start the development server
52
60
 
@@ -59,6 +67,14 @@ pnpm dev
59
67
 
60
68
  Open `http://localhost:3000` in your browser.
61
69
 
70
+ Start with these files:
71
+
72
+ - `geistdocs.tsx` for the site title, logo, navigation, repository, and AI prompt.
73
+ - `content/docs/index.mdx` for the documentation overview.
74
+ - `content/docs/meta.json` for sidebar order and groups.
75
+
76
+ Only customize `components/geistdocs/*`, `lib/geistdocs/*`, or route adapters when the generated defaults do not fit your site.
77
+
62
78
  ## Edit your first page
63
79
 
64
80
  Docs live in `content/docs`. Edit the overview page:
@@ -116,3 +132,13 @@ pnpm exec geistdocs update
116
132
  ```
117
133
 
118
134
  Review and test dependency changes before committing.
135
+
136
+ ## Verify and deploy
137
+
138
+ Run a production build before publishing:
139
+
140
+ ```bash title="Terminal"
141
+ pnpm build
142
+ ```
143
+
144
+ Then follow [Deploy to Vercel](/docs/deployment), including private package access and environment-variable setup.
@@ -200,7 +200,7 @@ Geistdocs applies a color for each method:
200
200
  | `PUT`, `PATCH` | Amber |
201
201
  | `DEL`, `DELETE` | Red |
202
202
 
203
- 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.
203
+ 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.
204
204
 
205
205
  ## Add links to the navigation
206
206
 
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