@vercel/geistdocs 1.25.1-canary.bd8995b → 1.25.1-canary.d2f4449

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 (140) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/components/blockquote.d.ts +3 -0
  3. package/dist/components/blockquote.d.ts.map +1 -0
  4. package/dist/components/blockquote.js +3 -0
  5. package/dist/components/callout.d.ts +13 -10
  6. package/dist/components/callout.d.ts.map +1 -1
  7. package/dist/components/callout.js +6 -6
  8. package/dist/components/code-block-tabs.d.ts.map +1 -1
  9. package/dist/components/code-block-tabs.js +3 -1
  10. package/dist/components/code-block.d.ts.map +1 -1
  11. package/dist/components/code-block.js +1 -1
  12. package/dist/components/command-prompt.d.ts.map +1 -1
  13. package/dist/components/command-prompt.js +15 -22
  14. package/dist/components/copy-prompt.d.ts +2 -1
  15. package/dist/components/copy-prompt.d.ts.map +1 -1
  16. package/dist/components/copy-prompt.js +2 -2
  17. package/dist/components/heading.d.ts +7 -0
  18. package/dist/components/heading.d.ts.map +1 -0
  19. package/dist/components/heading.js +14 -0
  20. package/dist/components/image.d.ts +19 -0
  21. package/dist/components/image.d.ts.map +1 -0
  22. package/dist/components/image.js +9 -0
  23. package/dist/components/table.d.ts +3 -0
  24. package/dist/components/table.d.ts.map +1 -0
  25. package/dist/components/table.js +3 -0
  26. package/dist/controls.d.ts.map +1 -1
  27. package/dist/controls.js +4 -3
  28. package/dist/internal/chat/activity.d.ts +20 -0
  29. package/dist/internal/chat/activity.d.ts.map +1 -0
  30. package/dist/internal/chat/activity.js +43 -0
  31. package/dist/internal/chat/context.d.ts +2 -0
  32. package/dist/internal/chat/context.d.ts.map +1 -1
  33. package/dist/internal/chat/context.js +24 -3
  34. package/dist/internal/chat/dots-spinner.d.ts.map +1 -1
  35. package/dist/internal/chat/dots-spinner.js +15 -9
  36. package/dist/internal/chat/loading-skeleton.d.ts +7 -0
  37. package/dist/internal/chat/loading-skeleton.d.ts.map +1 -0
  38. package/dist/internal/chat/loading-skeleton.js +46 -0
  39. package/dist/internal/chat/message-metadata.d.ts.map +1 -1
  40. package/dist/internal/chat/message-metadata.js +15 -30
  41. package/dist/internal/chat/message-sources.d.ts +3 -0
  42. package/dist/internal/chat/message-sources.d.ts.map +1 -0
  43. package/dist/internal/chat/message-sources.js +23 -0
  44. package/dist/internal/chat/message.d.ts.map +1 -1
  45. package/dist/internal/chat/message.js +59 -5
  46. package/dist/internal/chat/shell.d.ts.map +1 -1
  47. package/dist/internal/chat/shell.js +17 -17
  48. package/dist/internal/chat/source-chunks.d.ts +9 -0
  49. package/dist/internal/chat/source-chunks.d.ts.map +1 -0
  50. package/dist/internal/chat/source-chunks.js +7 -0
  51. package/dist/internal/chat/sources.d.ts +1 -1
  52. package/dist/internal/chat/sources.d.ts.map +1 -1
  53. package/dist/internal/chat/sources.js +7 -1
  54. package/dist/internal/link-href.d.ts +13 -0
  55. package/dist/internal/link-href.d.ts.map +1 -0
  56. package/dist/internal/link-href.js +51 -0
  57. package/dist/internal/mdx-to-markdown.d.ts +3 -0
  58. package/dist/internal/mdx-to-markdown.d.ts.map +1 -0
  59. package/dist/internal/mdx-to-markdown.js +134 -0
  60. package/dist/internal/mousedown-navigation-utils.d.ts +5 -0
  61. package/dist/internal/mousedown-navigation-utils.d.ts.map +1 -0
  62. package/dist/internal/mousedown-navigation-utils.js +95 -0
  63. package/dist/internal/mousedown-navigation.d.ts +10 -0
  64. package/dist/internal/mousedown-navigation.d.ts.map +1 -0
  65. package/dist/internal/mousedown-navigation.js +42 -0
  66. package/dist/internal/navbar/desktop-menu.js +1 -1
  67. package/dist/internal/navbar/mobile-menu.d.ts.map +1 -1
  68. package/dist/internal/navbar/mobile-menu.js +8 -13
  69. package/dist/internal/navbar/navbar-shell.d.ts.map +1 -1
  70. package/dist/internal/navbar/navbar-shell.js +2 -1
  71. package/dist/internal/page-actions-client.d.ts.map +1 -1
  72. package/dist/internal/page-actions-client.js +36 -32
  73. package/dist/internal/provider-client.d.ts.map +1 -1
  74. package/dist/internal/provider-client.js +29 -5
  75. package/dist/internal/react-node-text.d.ts +4 -0
  76. package/dist/internal/react-node-text.d.ts.map +1 -0
  77. package/dist/internal/react-node-text.js +11 -0
  78. package/dist/internal/search.d.ts.map +1 -1
  79. package/dist/internal/search.js +1 -1
  80. package/dist/internal/sidebar-responsive.d.ts +0 -1
  81. package/dist/internal/sidebar-responsive.d.ts.map +1 -1
  82. package/dist/internal/sidebar-responsive.js +0 -9
  83. package/dist/internal/sidebar-tree.d.ts.map +1 -1
  84. package/dist/internal/sidebar-tree.js +6 -1
  85. package/dist/internal/sidebar.d.ts.map +1 -1
  86. package/dist/internal/sidebar.js +78 -49
  87. package/dist/internal/table-of-contents.d.ts.map +1 -1
  88. package/dist/internal/table-of-contents.js +1 -1
  89. package/dist/internal/toc-items.d.ts.map +1 -1
  90. package/dist/internal/toc-items.js +18 -7
  91. package/dist/internal/ui/dropdown-menu.js +6 -6
  92. package/dist/internal/ui/navigation-menu.js +2 -2
  93. package/dist/internal/use-mobile.d.ts.map +1 -1
  94. package/dist/internal/use-mobile.js +2 -12
  95. package/dist/layout.d.ts +1 -0
  96. package/dist/layout.d.ts.map +1 -1
  97. package/dist/layout.js +2 -0
  98. package/dist/mdx.d.ts.map +1 -1
  99. package/dist/mdx.js +15 -1
  100. package/dist/pages/docs.d.ts.map +1 -1
  101. package/dist/pages/docs.js +17 -4
  102. package/dist/routes/chat.d.ts +1 -1
  103. package/dist/routes/chat.d.ts.map +1 -1
  104. package/dist/routes/chat.js +31 -14
  105. package/dist/routes/llms.d.ts +1 -1
  106. package/dist/routes/llms.d.ts.map +1 -1
  107. package/dist/routes/llms.js +12 -2
  108. package/dist/source.d.ts +10 -1
  109. package/dist/source.d.ts.map +1 -1
  110. package/dist/source.js +75 -34
  111. package/dist/versions.js +2 -2
  112. package/docs/agents.md +4 -3
  113. package/docs/llms.txt +378 -37
  114. package/docs/manifest.json +12 -3
  115. package/docs/pages/ask-ai.md +2 -2
  116. package/docs/pages/deployment.md +30 -5
  117. package/docs/pages/getting-started.md +38 -12
  118. package/docs/pages/guides/nested-navigation.md +1 -1
  119. package/docs/pages/md.md +25 -6
  120. package/docs/pages/migration-2.md +106 -0
  121. package/docs/pages/migration.md +5 -2
  122. package/docs/pages/syntax.md +163 -6
  123. package/docs/sitemap.md +3 -2
  124. package/package.json +12 -5
  125. package/template/app/[lang]/layout.tsx +4 -0
  126. package/template/app/styles/geistdocs.css +1 -1
  127. package/template/components/ui/button.tsx +1 -1
  128. package/template/content/docs/ask-ai.cn.mdx +2 -2
  129. package/template/content/docs/ask-ai.mdx +2 -2
  130. package/template/content/docs/deployment.mdx +31 -6
  131. package/template/content/docs/getting-started.mdx +39 -13
  132. package/template/content/docs/guides/nested-navigation.mdx +1 -1
  133. package/template/content/docs/md.mdx +25 -6
  134. package/template/content/docs/meta.json +1 -0
  135. package/template/content/docs/migration-2.mdx +106 -0
  136. package/template/content/docs/migration.mdx +5 -1
  137. package/template/content/docs/syntax.mdx +169 -6
  138. package/template/next.config.ts +9 -0
  139. package/template/package.json +4 -4
  140. package/theme.css +39 -105
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.bd8995b.
3
+ These docs are bundled with `@vercel/geistdocs` 1.25.1-canary.d2f4449.
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
  ---
@@ -1256,11 +1421,17 @@ Headings automatically generate anchor links for navigation and deep linking.
1256
1421
 
1257
1422
  Create unordered lists with `-`, `*`, or `+`:
1258
1423
 
1259
- - First item
1260
- - Second item
1261
- - Nested item
1262
- - Another nested item
1263
- - Third item
1424
+ ```md
1425
+ - Install the required packages
1426
+ - Configure your project
1427
+ - Start the development server
1428
+ ```
1429
+
1430
+ This renders as:
1431
+
1432
+ - Install the required packages
1433
+ - Configure your project
1434
+ - Start the development server
1264
1435
 
1265
1436
  Create ordered lists with numbers:
1266
1437
 
@@ -1272,7 +1443,91 @@ Create ordered lists with numbers:
1272
1443
 
1273
1444
  Use `>` to create blockquotes:
1274
1445
 
1275
- > This is a blockquote. You can use it to highlight important information or quotes from external sources.
1446
+ > **Watch:** Learn more about how to use `next/image` → [YouTube (9 minutes)](https://youtu.be/IU_qq_c_lKA).
1447
+
1448
+ ### Callouts
1449
+
1450
+ Use `<Callout>` for a highlighted informational note:
1451
+
1452
+ ```mdx
1453
+ <Callout>This is automatically set when deploying to Vercel.</Callout>
1454
+ ```
1455
+
1456
+ This renders as:
1457
+
1458
+ > This is automatically set when deploying to Vercel.
1459
+
1460
+ Callouts can also contain a title and lists:
1461
+
1462
+ > Note:
1463
+ - The `App Router` uses [React canary
1464
+ releases](https://react.dev/blog/2023/05/03/react-canaries) built-in, which
1465
+ include all the stable React 19 changes, as well as newer features being
1466
+ validated in frameworks, but you should still declare react and react-dom in
1467
+ package.json for tooling and ecosystem compatibility.
1468
+ - The `Pages Router` uses the React version from your `package.json`.
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
+
1497
+ ### Copy Prompts
1498
+
1499
+ Short prompts render in full without an expansion control:
1500
+
1501
+ ```mdx
1502
+ <CopyPrompt text="Summarize this documentation page and list the key concepts.">
1503
+ Summarize this documentation page and list the key concepts.
1504
+ </CopyPrompt>
1505
+ ```
1506
+
1507
+ This renders as:
1508
+
1509
+ Summarize this documentation page and list the key concepts.
1510
+
1511
+ Long prompts initially show a preview with a **Show more** control:
1512
+
1513
+ ```mdx
1514
+ <CopyPrompt collapsible text="Write a detailed migration plan for this project.">
1515
+ Write a detailed migration plan for this project. Include prerequisites,
1516
+ implementation steps, validation, rollback guidance, and common pitfalls.
1517
+ </CopyPrompt>
1518
+ ```
1519
+
1520
+ Set the boolean `collapsible` prop when the prompt should initially render as a
1521
+ two-line preview. This renders as:
1522
+
1523
+ Review this Geistdocs project in detail. Explain how the `@vercel/geistdocs`
1524
+ package, application layouts, local adapter files, source configuration,
1525
+ `content/docs` directory, navigation metadata, MDX components, syntax
1526
+ highlighting, search routes, and deployment configuration work together.
1527
+ Then identify the safest first files to edit, describe the effect of each
1528
+ change, call out common mistakes, and propose a step-by-step plan for
1529
+ customizing the documentation site without breaking routing, generated
1530
+ Markdown, or accessibility behavior.
1276
1531
 
1277
1532
  ### Links
1278
1533
 
@@ -1281,6 +1536,25 @@ Create links with `[text](url)`:
1281
1536
  - [External link](https://vercel.com)
1282
1537
  - [Internal link](/docs/getting-started)
1283
1538
 
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:
1542
+
1543
+ ```md
1544
+ [External link](https://vercel.com)
1545
+ [Internal link](/docs/getting-started)
1546
+ ```
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
+
1284
1558
  ### Images
1285
1559
 
1286
1560
  Add images with `![alt text](url)`:
@@ -1289,6 +1563,44 @@ Add images with `![alt text](url)`:
1289
1563
  ![Description of the image](/path/to/image.png)
1290
1564
  ```
1291
1565
 
1566
+ Use `<Image>` when an image needs the standard documentation presentation and
1567
+ an optional description. It uses Geistcn's image component without a lightbox
1568
+ or other interaction:
1569
+
1570
+ ```mdx
1571
+ <Image
1572
+ alt="Deployment graph"
1573
+ caption="Requests move from the edge to the selected region."
1574
+ height={480}
1575
+ src="/deployment-graph.png"
1576
+ width={800}
1577
+ />
1578
+ ```
1579
+
1580
+ This renders as:
1581
+
1582
+ <Image
1583
+ alt="Navigation Inspector showing a loading shell for a page load"
1584
+ caption="The Navigation Inspector paused on a page load."
1585
+ height={389}
1586
+ srcDark="https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/dark/inspector-load.png"
1587
+ srcLight="https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/light/inspector-load.png"
1588
+ width={472}
1589
+ />
1590
+
1591
+ For theme-aware images, provide both sources:
1592
+
1593
+ ```mdx
1594
+ <Image
1595
+ alt="Deployment graph"
1596
+ caption="Requests move from the edge to the selected region."
1597
+ height={480}
1598
+ srcDark="/deployment-graph-dark.png"
1599
+ srcLight="/deployment-graph-light.png"
1600
+ width={800}
1601
+ />
1602
+ ```
1603
+
1292
1604
  ## GitHub Flavored Markdown
1293
1605
 
1294
1606
  Geistdocs supports GFM extensions including tables, task lists, and autolinks.
@@ -1313,6 +1625,16 @@ This renders as:
1313
1625
  | GFM | GitHub extensions | Supported |
1314
1626
  | MDX | JSX in Markdown | Supported |
1315
1627
 
1628
+ Tables can also include inline code, as commonly used for file references:
1629
+
1630
+ | File | Description |
1631
+ | -------------------- | ------------------------------------------------ |
1632
+ | `next.config.js` | Configuration file for Next.js |
1633
+ | `package.json` | Project dependencies and scripts |
1634
+ | `instrumentation.ts` | OpenTelemetry and instrumentation file |
1635
+ | `.env.local` | Local environment variables |
1636
+ | `tsconfig.json` | Configuration file for TypeScript |
1637
+
1316
1638
  ### Task Lists
1317
1639
 
1318
1640
  Create interactive task lists:
@@ -2324,7 +2646,7 @@ related:
2324
2646
 
2325
2647
  # .md Extension
2326
2648
 
2327
- Geistdocs lets AI tools and language models access documentation pages as plain Markdown. Append `.md` or `.mdx` to a documentation URL to get the processed Markdown content for that page.
2649
+ Geistdocs lets AI tools and language models access documentation pages as plain Markdown. Append `.md` or `.mdx` to a documentation URL to get the page content with presentation-only MDX components removed.
2328
2650
 
2329
2651
  Help me test raw Markdown routes in this Geistdocs project. Fetch a docs page with `.mdx` appended, compare it to the rendered page, and explain how AI tools can use it.
2330
2652
 
@@ -2344,13 +2666,13 @@ https://yourdomain.com/docs/getting-started.mdx
2344
2666
 
2345
2667
  The `.mdx` version returns:
2346
2668
 
2347
- - The page title as an H1 heading
2348
- - The full processed Markdown content
2669
+ - Frontmatter with the canonical page URL, docs index, and last-updated date when available
2670
+ - The full page content as plain Markdown
2349
2671
  - No HTML, styling, or navigation
2350
2672
 
2351
2673
  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`.
2352
2674
 
2353
- 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.
2675
+ 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.
2354
2676
 
2355
2677
  ## Use cases
2356
2678
 
@@ -2394,11 +2716,30 @@ The response includes:
2394
2716
 
2395
2717
  - Content-Type: `text/markdown`
2396
2718
  - `Link: <canonical page URL>; rel="canonical"` for resolved pages
2397
- - The page title as a level 1 heading
2398
- - Processed Markdown content from Fumadocs
2719
+ - Frontmatter with page metadata and discovery links
2720
+ - Page content with presentation-only MDX components removed
2399
2721
 
2400
2722
  All MDX components are processed and converted to plain Markdown equivalents.
2401
2723
 
2724
+ ### Customize frontmatter
2725
+
2726
+ Geistdocs generates `title`, `description`, `url`, `docs_index`, and `lastUpdated` when their values are available, along with supported page frontmatter such as `prerequisites` and `related`. Add product-specific fields or override defaults with the source `markdown.frontmatter` hook:
2727
+
2728
+ ```ts title="lib/geistdocs/source.ts"
2729
+ export const geistdocsSource = createSource({
2730
+ config,
2731
+ docs,
2732
+ markdown: {
2733
+ frontmatter: (defaults) => ({
2734
+ docs_index: "/docs/llms.txt",
2735
+ version: "16.3.4",
2736
+ }),
2737
+ },
2738
+ });
2739
+ ```
2740
+
2741
+ The callback returns only additions and overrides; Geistdocs keeps the remaining generated fields from `defaults`.
2742
+
2402
2743
  ## Missing documentation pages
2403
2744
 
2404
2745
  When a Markdown request does not match a page, Geistdocs returns an agent-readable `Page Not Found` response. It compares the requested path with visible page paths and titles, then links up to five likely matches with their descriptions. If no match is useful, the response links to `/llms.txt` instead.
@@ -2682,7 +3023,7 @@ In this mode, Geistdocs uses the local `search_docs` tool during the AI SDK `str
2682
3023
 
2683
3024
  #### Choose a model
2684
3025
 
2685
- 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`.
3026
+ 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`.
2686
3027
 
2687
3028
  ```ts title="app/api/chat/route.ts"
2688
3029
  import { createChatRoute } from "@vercel/geistdocs/routes/chat";
@@ -2791,7 +3132,7 @@ The chat interface adapts to different screen sizes:
2791
3132
 
2792
3133
  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.
2793
3134
 
2794
- 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.
3135
+ 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.
2795
3136
 
2796
3137
  ## Suggested Prompts
2797
3138
 
@@ -3002,7 +3343,7 @@ Geistdocs applies a color for each method:
3002
3343
  | `PUT`, `PATCH` | Amber |
3003
3344
  | `DEL`, `DELETE` | Red |
3004
3345
 
3005
- 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.
3346
+ 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.
3006
3347
 
3007
3348
  ## Add links to the navigation
3008
3349
 
@@ -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.bd8995b"
211
+ "version": "1.25.1-canary.d2f4449"
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