@vercel/geistdocs 1.25.1-canary.f56ac48 → 1.25.1-canary.fb7a9dd

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 (114) 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 +1 -1
  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/copy-prompt.js +1 -1
  8. package/dist/components/image.d.ts +19 -0
  9. package/dist/components/image.d.ts.map +1 -0
  10. package/dist/components/image.js +9 -0
  11. package/dist/components/steps.d.ts +9 -0
  12. package/dist/components/steps.d.ts.map +1 -0
  13. package/dist/components/steps.js +9 -0
  14. package/dist/internal/chat/activity.d.ts +20 -0
  15. package/dist/internal/chat/activity.d.ts.map +1 -0
  16. package/dist/internal/chat/activity.js +43 -0
  17. package/dist/internal/chat/message-metadata.d.ts.map +1 -1
  18. package/dist/internal/chat/message-metadata.js +15 -30
  19. package/dist/internal/chat/message-sources.d.ts +3 -0
  20. package/dist/internal/chat/message-sources.d.ts.map +1 -0
  21. package/dist/internal/chat/message-sources.js +23 -0
  22. package/dist/internal/chat/message.d.ts.map +1 -1
  23. package/dist/internal/chat/message.js +44 -10
  24. package/dist/internal/chat/shell.d.ts.map +1 -1
  25. package/dist/internal/chat/shell.js +7 -2
  26. package/dist/internal/chat/source-chunks.d.ts +9 -0
  27. package/dist/internal/chat/source-chunks.d.ts.map +1 -0
  28. package/dist/internal/chat/source-chunks.js +7 -0
  29. package/dist/internal/chat/sources.d.ts +1 -1
  30. package/dist/internal/chat/sources.d.ts.map +1 -1
  31. package/dist/internal/chat/sources.js +6 -3
  32. package/dist/internal/link-href.d.ts +13 -0
  33. package/dist/internal/link-href.d.ts.map +1 -0
  34. package/dist/internal/link-href.js +51 -0
  35. package/dist/internal/mdx-to-markdown.d.ts +3 -0
  36. package/dist/internal/mdx-to-markdown.d.ts.map +1 -0
  37. package/dist/internal/mdx-to-markdown.js +166 -0
  38. package/dist/internal/mousedown-navigation-utils.d.ts +5 -0
  39. package/dist/internal/mousedown-navigation-utils.d.ts.map +1 -0
  40. package/dist/internal/mousedown-navigation-utils.js +95 -0
  41. package/dist/internal/mousedown-navigation.d.ts +10 -0
  42. package/dist/internal/mousedown-navigation.d.ts.map +1 -0
  43. package/dist/internal/mousedown-navigation.js +42 -0
  44. package/dist/internal/navbar/navbar-shell.d.ts.map +1 -1
  45. package/dist/internal/navbar/navbar-shell.js +2 -1
  46. package/dist/internal/provider-client.d.ts.map +1 -1
  47. package/dist/internal/provider-client.js +1 -11
  48. package/dist/internal/react-node-text.d.ts +4 -0
  49. package/dist/internal/react-node-text.d.ts.map +1 -0
  50. package/dist/internal/react-node-text.js +11 -0
  51. package/dist/internal/search.js +1 -1
  52. package/dist/internal/sidebar-tree.d.ts.map +1 -1
  53. package/dist/internal/sidebar-tree.js +6 -1
  54. package/dist/internal/sidebar.d.ts.map +1 -1
  55. package/dist/internal/sidebar.js +15 -14
  56. package/dist/internal/table-of-contents-visibility.d.ts +27 -0
  57. package/dist/internal/table-of-contents-visibility.d.ts.map +1 -0
  58. package/dist/internal/table-of-contents-visibility.js +15 -0
  59. package/dist/internal/toc-items.d.ts.map +1 -1
  60. package/dist/internal/toc-items.js +2 -1
  61. package/dist/mdx.d.ts +1 -0
  62. package/dist/mdx.d.ts.map +1 -1
  63. package/dist/mdx.js +7 -4
  64. package/dist/page.d.ts +35 -0
  65. package/dist/page.d.ts.map +1 -0
  66. package/dist/page.js +26 -0
  67. package/dist/pages/docs.d.ts +6 -0
  68. package/dist/pages/docs.d.ts.map +1 -1
  69. package/dist/pages/docs.js +29 -17
  70. package/dist/routes/chat.d.ts.map +1 -1
  71. package/dist/routes/chat.js +30 -13
  72. package/dist/routes/llms.d.ts +1 -1
  73. package/dist/routes/llms.d.ts.map +1 -1
  74. package/dist/routes/llms.js +12 -2
  75. package/dist/source-config.d.ts +11 -0
  76. package/dist/source-config.d.ts.map +1 -1
  77. package/dist/source-config.js +21 -2
  78. package/dist/source.d.ts +10 -1
  79. package/dist/source.d.ts.map +1 -1
  80. package/dist/source.js +75 -34
  81. package/dist/versions.js +2 -2
  82. package/docs/agents.md +6 -3
  83. package/docs/llms.txt +495 -33
  84. package/docs/manifest.json +30 -3
  85. package/docs/pages/components/steps.md +129 -0
  86. package/docs/pages/deployment.md +30 -5
  87. package/docs/pages/getting-started.md +38 -12
  88. package/docs/pages/guides/hidden-outline.md +31 -0
  89. package/docs/pages/guides/nested-navigation.md +1 -1
  90. package/docs/pages/md.md +24 -5
  91. package/docs/pages/migration-2.md +106 -0
  92. package/docs/pages/migration.md +5 -2
  93. package/docs/pages/syntax.md +73 -5
  94. package/docs/pages/table-of-contents.md +40 -0
  95. package/docs/sitemap.md +5 -2
  96. package/package.json +19 -5
  97. package/source-config.js +38 -2
  98. package/template/app/[lang]/docs/custom-page/page.tsx +49 -0
  99. package/template/content/docs/components/meta.json +4 -0
  100. package/template/content/docs/components/steps.mdx +125 -0
  101. package/template/content/docs/deployment.mdx +31 -6
  102. package/template/content/docs/getting-started.mdx +39 -13
  103. package/template/content/docs/guides/hidden-outline.mdx +28 -0
  104. package/template/content/docs/guides/meta.json +1 -1
  105. package/template/content/docs/guides/nested-navigation.mdx +1 -1
  106. package/template/content/docs/md.mdx +24 -5
  107. package/template/content/docs/meta.json +3 -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 +74 -5
  111. package/template/content/docs/table-of-contents.mdx +40 -0
  112. package/template/next.config.ts +9 -0
  113. package/template/package.json +4 -4
  114. package/theme.css +56 -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.f56ac48.
3
+ These docs are bundled with `@vercel/geistdocs` 1.25.1-canary.fb7a9dd.
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.
@@ -21,10 +22,12 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
21
22
  - [Configure sidebar navigation](pages/guides/nested-navigation.md): Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.
22
23
  - [Edit on GitHub](pages/edit-on-github.md): A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
23
24
  - [Feedback](pages/feedback.md): An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
25
+ - [Hide the outline](pages/guides/hidden-outline.md): Example page with tableOfContents set to false in frontmatter. The outline column is hidden and the content spans that column, while page actions stay in place.
24
26
  - [Internationalization](pages/internationalization.md): Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
25
27
  - [llms.txt](pages/llms-txt.md): A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
26
28
  - [Open in Chat](pages/open-in-chat.md): Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
27
29
  - [RSS](pages/rss.md): An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
30
+ - [Steps](pages/components/steps.md): Write consecutive headings that start with a number, such as "### 1. Install", to render a numbered step list. The Steps and Step components cover cases where a heading must be wrapped in another component.
28
31
  - [Table of contents](pages/table-of-contents.md): Geistdocs builds the "On this page" outline from your headings, indents sub-headings under their parent, and tracks the active section along a straight vertical guide rail.
29
32
 
30
33
  ---
@@ -148,39 +151,47 @@ related:
148
151
 
149
152
  # Getting Started
150
153
 
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.
154
+ 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
155
 
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`.
156
+ 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
157
 
155
158
  ## Prerequisites
156
159
 
157
160
  Before you begin, install:
158
161
 
159
- - Node.js 18 or later
160
- - pnpm, npm, or another package manager
162
+ - Node.js 20.9 or later
163
+ - pnpm
161
164
  - Git
162
165
 
163
- ## Create a project
166
+ The CLI always uses pnpm to install the generated project's dependencies.
164
167
 
165
- Run the Geistdocs CLI from an empty parent folder:
168
+ ## Authenticate package access
166
169
 
167
- ```bash title="Terminal"
168
- pnpm dlx @vercel/geistdocs init --name my-docs
170
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Configure your user-level `~/.npmrc` before running the CLI:
171
+
172
+ ```ini title="~/.npmrc"
173
+ @vercel:registry=https://registry.npmjs.org/
174
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
175
+ always-auth=true
169
176
  ```
170
177
 
171
- You can also use npm:
178
+ 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.
179
+
180
+ ## Create a project
181
+
182
+ Run the Geistdocs CLI from an empty parent folder:
172
183
 
173
184
  ```bash title="Terminal"
174
- npx @vercel/geistdocs init --name my-docs
185
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
175
186
  ```
176
187
 
177
188
  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
189
 
179
190
  ## Understand generated dependencies
180
191
 
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.
192
+ 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
193
 
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.
194
+ Keep those integrations package-backed. Update Geistdocs instead of copying package internals into the app.
184
195
 
185
196
  ## Start the development server
186
197
 
@@ -193,6 +204,14 @@ pnpm dev
193
204
 
194
205
  Open `http://localhost:3000` in your browser.
195
206
 
207
+ Start with these files:
208
+
209
+ - `geistdocs.tsx` for the site title, logo, navigation, repository, and AI prompt.
210
+ - `content/docs/index.mdx` for the documentation overview.
211
+ - `content/docs/meta.json` for sidebar order and groups.
212
+
213
+ Only customize `components/geistdocs/*`, `lib/geistdocs/*`, or route adapters when the generated defaults do not fit your site.
214
+
196
215
  ## Edit your first page
197
216
 
198
217
  Docs live in `content/docs`. Edit the overview page:
@@ -251,6 +270,16 @@ pnpm exec geistdocs update
251
270
 
252
271
  Review and test dependency changes before committing.
253
272
 
273
+ ## Verify and deploy
274
+
275
+ Run a production build before publishing:
276
+
277
+ ```bash title="Terminal"
278
+ pnpm build
279
+ ```
280
+
281
+ Then follow [Deploy to Vercel](/docs/deployment), including private package access and environment-variable setup.
282
+
254
283
 
255
284
  ---
256
285
 
@@ -324,7 +353,7 @@ Set this variable explicitly when deploying outside Vercel. Use a hostname such
324
353
  title: Deploy to Vercel
325
354
  description: Learn how to deploy your Geistdocs site to Vercel
326
355
  type: guide
327
- summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
356
+ summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
328
357
  url: /docs/deployment
329
358
  source: apps/template/content/docs/deployment.mdx
330
359
  prerequisites:
@@ -336,9 +365,9 @@ related:
336
365
 
337
366
  # Deploy to Vercel
338
367
 
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.
368
+ Deploy a Geistdocs site to Vercel as a Next.js app. Configure private package access, environment variables, and the production URL before shipping.
340
369
 
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.
370
+ 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
371
 
343
372
  ## Prerequisites
344
373
 
@@ -348,6 +377,31 @@ Before deploying, you need:
348
377
  - A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
349
378
  - Your Vercel account connected to your GitHub account
350
379
  - Environment variables ready (see [Environment Variables](/docs/env))
380
+ - Access to the restricted `@vercel` npm packages
381
+
382
+ ## Configure private package access
383
+
384
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Package installation fails without npm authentication.
385
+
386
+ 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.
387
+
388
+ For GitHub Actions, ask `#help-it` to allow the repository to use the `NPM_TOKEN` organization secret, then pass it to the install step:
389
+
390
+ ```yaml title=".github/workflows/check.yml"
391
+ - uses: pnpm/action-setup@v4
392
+
393
+ - uses: actions/setup-node@v4
394
+ with:
395
+ node-version: 20
396
+ cache: pnpm
397
+ registry-url: https://registry.npmjs.org
398
+
399
+ - run: pnpm install
400
+ env:
401
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
402
+ ```
403
+
404
+ 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
405
 
352
406
  ## Deploy to Vercel
353
407
 
@@ -357,9 +411,9 @@ To deploy from the Vercel dashboard:
357
411
  2. Select your Geistdocs repository
358
412
  3. Configure your project settings:
359
413
  - **Framework Preset**: Next.js (automatically detected)
360
- - **Build Command**: `pnpm build` or `npm run build`
414
+ - **Build Command**: `pnpm build`
361
415
  - **Output Directory**: `.next` (default)
362
- - **Install Command**: `pnpm install` or `npm install`
416
+ - **Install Command**: `pnpm install`
363
417
  4. Add your environment variables (see [Environment Variables](/docs/env))
364
418
  5. Click "Deploy"
365
419
 
@@ -378,7 +432,7 @@ The Geistdocs site does not need Vertex credentials. The platform proxy authenti
378
432
  ---
379
433
 
380
434
  ---
381
- title: Migration guide
435
+ title: Migrate to Geistdocs
382
436
  description: Migrate a Fumadocs or custom Geist docs site to package-backed Geistdocs
383
437
  type: guide
384
438
  summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
@@ -393,10 +447,13 @@ related:
393
447
  - /docs/agent-readiness
394
448
  ---
395
449
 
396
- # Migration guide
450
+ # Migrate to Geistdocs
397
451
 
398
452
  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
453
 
454
+ > Note:
455
+ 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.
456
+
400
457
  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
458
 
402
459
  ## Before you migrate
@@ -804,6 +861,116 @@ Check these URLs locally:
804
861
  - Read [Agent readiness](/docs/agent-readiness) to configure `/agents.md` and `/.well-known/mcp.json` for AI agents.
805
862
 
806
863
 
864
+ ---
865
+
866
+ ---
867
+ title: Migrate from Geistdocs 1.x to 2.0
868
+ description: Upgrade imports, dependencies, and routing without copying Geistdocs internals
869
+ type: guide
870
+ summary: A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.
871
+ url: /docs/migration-2
872
+ source: apps/template/content/docs/migration-2.mdx
873
+ related:
874
+ - /docs/migration
875
+ - /docs/configuration
876
+ - /docs/versioned-docs
877
+ - /docs/proxy
878
+ ---
879
+
880
+ # Migrate from Geistdocs 1.x to 2.0
881
+
882
+ 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.
883
+
884
+ 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.
885
+
886
+ ## 1. Upgrade dependencies
887
+
888
+ ```bash title="Terminal"
889
+ 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
890
+ ```
891
+
892
+ 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.
893
+
894
+ ## 2. Replace removed imports
895
+
896
+ | Geistdocs 1.x import | Geistdocs 2.0 replacement |
897
+ | --- | --- |
898
+ | `badge`, `button`, `dialog`, `drawer`, `input`, `kbd`, `separator`, `sheet`, `spinner`, `textarea`, `theme-switcher`, or `tooltip` | Import the matching component from `@vercel/geistcn/components/<name>`. |
899
+ | `switch` | Use `@vercel/geistcn/components/toggle`. |
900
+ | `sonner` | Use `Toasts` and `useToasts` from `@vercel/geistcn/components/toasts`. |
901
+ | `theme-aware-image` | Use Geistcn `Image` with `srcLight` and `srcDark`. |
902
+ | `button-group`, `card`, or `input-group` | Choose a Geistcn component or keep an app-owned composition; there is no API-compatible replacement. |
903
+ | `@vercel/geistdocs/assets/icons` or `assets/icons/*` | `@vercel/geistcn-assets/icons` or `icons/*` |
904
+ | `@vercel/geistdocs/assets/logos` or `assets/logos/*` | `@vercel/geistcn-assets/logos` or `logos/*` |
905
+
906
+ Keep documentation-specific imports such as `callout`, `code-block`, `code-block-tabs`, `collapsible`, `command-prompt`, `copy-prompt`, `mermaid`, and `video` on `@vercel/geistdocs/components/*`.
907
+
908
+ Import the package stylesheet once and apply the Geist font classes at the root:
909
+
910
+ ```tsx title="app/[lang]/layout.tsx"
911
+ import "@vercel/geistdocs/styles.css";
912
+ import { geistFontClasses } from "@vercel/geistcn/core";
913
+
914
+ export default function RootLayout({ children }: LayoutProps<"/[lang]">) {
915
+ return (
916
+ <html className={geistFontClasses}>
917
+ <body>{children}</body>
918
+ </html>
919
+ );
920
+ }
921
+ ```
922
+
923
+ ## 3. Use the Next.js and source integrations
924
+
925
+ ```ts title="next.config.ts"
926
+ import { createGeistdocs } from "@vercel/geistdocs/next";
927
+ import type { NextConfig } from "next";
928
+
929
+ const config: NextConfig = {
930
+ modularizeImports: {
931
+ "@vercel/geistcn/components": {
932
+ skipDefaultConversion: true,
933
+ transform: "@vercel/geistcn/components/{{ kebabCase member }}",
934
+ },
935
+ "@vercel/geistcn/core": {
936
+ skipDefaultConversion: true,
937
+ transform: "@vercel/geistcn/core",
938
+ },
939
+ },
940
+ transpilePackages: [
941
+ "@vercel/geistcn",
942
+ "@vercel/geist-test-utils",
943
+ "@vercel/next-themes",
944
+ ],
945
+ cacheComponents: true,
946
+ partialPrefetching: true,
947
+ };
948
+
949
+ export default createGeistdocs()(config);
950
+ ```
951
+
952
+ 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.
953
+
954
+ ## 4. Preserve routing invariants
955
+
956
+ - If Next.js uses `basePath`, set the same value in Geistdocs config.
957
+ - 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.
958
+ - For versioned docs, use `createVersionedSources` and pass server-computed `collectVersionSwitchPaths` to the version selector so missing pages fall back to an existing ancestor.
959
+ - 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.
960
+ - Keep product-specific navigation titles, badges, related links, and content transforms in the app.
961
+
962
+ ## 5. Verify the upgrade
963
+
964
+ - Run install, typecheck, tests, and a production build.
965
+ - Open representative HTML pages and their `.md` equivalents, including a not-found path.
966
+ - Test search, Ask AI citations, proxy rewrites, and agent-readable routes.
967
+ - Switch versions from pages that do and do not exist in the target version.
968
+ - Confirm links do not trigger broad post-load prefetching and Ask AI is not eagerly loaded.
969
+ - Recheck LCP, CLS, accessibility, and post-render network and CPU activity.
970
+
971
+ For a first migration from Fumadocs or a custom docs site, follow the [full migration guide](/docs/migration).
972
+
973
+
807
974
  ---
808
975
 
809
976
  ---
@@ -1274,6 +1441,10 @@ Create ordered lists with numbers:
1274
1441
  2. Second step
1275
1442
  3. Third step
1276
1443
 
1444
+ ### Steps
1445
+
1446
+ Headings that start with a number, such as `### 1. Install the CLI`, render as a numbered step list with a counter beside each heading. See [Steps](/docs/components/steps) for the grouping rules and the `Steps` and `Step` components.
1447
+
1277
1448
  ### Blockquotes
1278
1449
 
1279
1450
  Use `>` to create blockquotes:
@@ -1302,6 +1473,33 @@ Callouts can also contain a title and lists:
1302
1473
  package.json for tooling and ecosystem compatibility.
1303
1474
  - The `Pages Router` uses the React version from your `package.json`.
1304
1475
 
1476
+ Callouts support rich inline Markdown, including code, emphasis, and links:
1477
+
1478
+ ```mdx
1479
+ <Callout title="Good to know">
1480
+ Global styles can be imported into any layout, page, or component inside the
1481
+ `app` directory. However, since Next.js uses React's built-in support for
1482
+ stylesheets to integrate with Suspense, this currently does not remove
1483
+ stylesheets as you navigate between routes which can lead to conflicts. We
1484
+ recommend using global styles for _truly global_ CSS (like Tailwind's base
1485
+ styles), [Tailwind CSS](https://tailwindcss.com) for component styling, and
1486
+ [CSS Modules](https://nextjs.org/docs/app/getting-started/css#css-modules) for
1487
+ custom scoped CSS when needed.
1488
+ </Callout>
1489
+ ```
1490
+
1491
+ This renders as:
1492
+
1493
+ > Note:
1494
+ Global styles can be imported into any layout, page, or component inside the
1495
+ `app` directory. However, since Next.js uses React's built-in support for
1496
+ stylesheets to integrate with Suspense, this currently does not remove
1497
+ stylesheets as you navigate between routes which can lead to conflicts. We
1498
+ recommend using global styles for _truly global_ CSS (like Tailwind's base
1499
+ styles), [Tailwind CSS](https://tailwindcss.com) for component styling, and
1500
+ [CSS Modules](https://nextjs.org/docs/app/getting-started/css#css-modules) for
1501
+ custom scoped CSS when needed.
1502
+
1305
1503
  ### Copy Prompts
1306
1504
 
1307
1505
  Short prompts render in full without an expansion control:
@@ -1344,17 +1542,16 @@ Create links with `[text](url)`:
1344
1542
  - [External link](https://vercel.com)
1345
1543
  - [Internal link](/docs/getting-started)
1346
1544
 
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:
1545
+ Use an absolute `https://` or `http://` URL for an external destination. Use a
1546
+ root-relative path beginning with `/` for an internal link. Both use the same
1547
+ visual styling:
1350
1548
 
1351
1549
  ```md
1352
1550
  [External link](https://vercel.com)
1353
1551
  [Internal link](/docs/getting-started)
1354
1552
  ```
1355
1553
 
1356
- External links can also contain inline code. The underline applies to the text,
1357
- but not the external-link icon:
1554
+ Links can also contain inline code:
1358
1555
 
1359
1556
  ```md
1360
1557
  Run independent requests in parallel with [`Promise.all`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/all).
@@ -1372,6 +1569,44 @@ Add images with `![alt text](url)`:
1372
1569
  ![Description of the image](/path/to/image.png)
1373
1570
  ```
1374
1571
 
1572
+ Use `<Image>` when an image needs the standard documentation presentation and
1573
+ an optional description. It uses Geistcn's image component without a lightbox
1574
+ or other interaction:
1575
+
1576
+ ```mdx
1577
+ <Image
1578
+ alt="Deployment graph"
1579
+ caption="Requests move from the edge to the selected region."
1580
+ height={480}
1581
+ src="/deployment-graph.png"
1582
+ width={800}
1583
+ />
1584
+ ```
1585
+
1586
+ This renders as:
1587
+
1588
+ <Image
1589
+ alt="Navigation Inspector showing a loading shell for a page load"
1590
+ caption="The Navigation Inspector paused on a page load."
1591
+ height={389}
1592
+ srcDark="https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/dark/inspector-load.png"
1593
+ srcLight="https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/light/inspector-load.png"
1594
+ width={472}
1595
+ />
1596
+
1597
+ For theme-aware images, provide both sources:
1598
+
1599
+ ```mdx
1600
+ <Image
1601
+ alt="Deployment graph"
1602
+ caption="Requests move from the edge to the selected region."
1603
+ height={480}
1604
+ srcDark="/deployment-graph-dark.png"
1605
+ srcLight="/deployment-graph-light.png"
1606
+ width={800}
1607
+ />
1608
+ ```
1609
+
1375
1610
  ## GitHub Flavored Markdown
1376
1611
 
1377
1612
  Geistdocs supports GFM extensions including tables, task lists, and autolinks.
@@ -2417,7 +2652,7 @@ related:
2417
2652
 
2418
2653
  # .md Extension
2419
2654
 
2420
- 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.
2655
+ 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.
2421
2656
 
2422
2657
  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.
2423
2658
 
@@ -2437,8 +2672,8 @@ https://yourdomain.com/docs/getting-started.mdx
2437
2672
 
2438
2673
  The `.mdx` version returns:
2439
2674
 
2440
- - The page title as an H1 heading
2441
- - The full processed Markdown content
2675
+ - Frontmatter with the canonical page URL, docs index, and last-updated date when available
2676
+ - The full page content as plain Markdown
2442
2677
  - No HTML, styling, or navigation
2443
2678
 
2444
2679
  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`.
@@ -2487,11 +2722,30 @@ The response includes:
2487
2722
 
2488
2723
  - Content-Type: `text/markdown`
2489
2724
  - `Link: <canonical page URL>; rel="canonical"` for resolved pages
2490
- - The page title as a level 1 heading
2491
- - Processed Markdown content from Fumadocs
2725
+ - Frontmatter with page metadata and discovery links
2726
+ - Page content with presentation-only MDX components removed
2492
2727
 
2493
2728
  All MDX components are processed and converted to plain Markdown equivalents.
2494
2729
 
2730
+ ### Customize frontmatter
2731
+
2732
+ 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:
2733
+
2734
+ ```ts title="lib/geistdocs/source.ts"
2735
+ export const geistdocsSource = createSource({
2736
+ config,
2737
+ docs,
2738
+ markdown: {
2739
+ frontmatter: (defaults) => ({
2740
+ docs_index: "/docs/llms.txt",
2741
+ version: "16.3.4",
2742
+ }),
2743
+ },
2744
+ });
2745
+ ```
2746
+
2747
+ The callback returns only additions and overrides; Geistdocs keeps the remaining generated fields from `defaults`.
2748
+
2495
2749
  ## Missing documentation pages
2496
2750
 
2497
2751
  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.
@@ -3095,7 +3349,7 @@ Geistdocs applies a color for each method:
3095
3349
  | `PUT`, `PATCH` | Amber |
3096
3350
  | `DEL`, `DELETE` | Red |
3097
3351
 
3098
- 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.
3352
+ 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.
3099
3353
 
3100
3354
  ## Add links to the navigation
3101
3355
 
@@ -3282,6 +3536,41 @@ Pass any additional fields in the request body, and they are captured as metadat
3282
3536
  - Custom tracking data
3283
3537
 
3284
3538
 
3539
+ ---
3540
+
3541
+ ---
3542
+ title: Hide the outline
3543
+ description: A page that sets tableOfContents to false so the On this page outline is not rendered and the content spans its column
3544
+ type: guide
3545
+ summary: Example page with tableOfContents set to false in frontmatter. The outline column is hidden and the content spans that column, while page actions stay in place.
3546
+ url: /docs/guides/hidden-outline
3547
+ source: apps/template/content/docs/guides/hidden-outline.mdx
3548
+ related:
3549
+ - /docs/table-of-contents
3550
+ ---
3551
+
3552
+ # Hide the outline
3553
+
3554
+ This page sets `tableOfContents: false` in its frontmatter, so the **On this page** outline does not render on desktop even though the page has headings.
3555
+
3556
+ ```yaml
3557
+ ---
3558
+ title: Hide the outline
3559
+ tableOfContents: false
3560
+ ---
3561
+ ```
3562
+
3563
+ ## When to hide the outline
3564
+
3565
+ Hide the outline on pages where it would repeat the content, such as overviews made of cards or short pages with one or two sections. Long reference pages should keep it.
3566
+
3567
+ ## What stays the same
3568
+
3569
+ The breadcrumb, page actions, and previous and next links stay in place. The content extends across the column the outline would have used, so the page keeps the same right edge as pages that show an outline.
3570
+
3571
+ See [Table of contents](/docs/table-of-contents) for the complete behavior.
3572
+
3573
+
3285
3574
  ---
3286
3575
 
3287
3576
  ---
@@ -3707,6 +3996,139 @@ lastModified: 2025-11-12
3707
3996
  Git commit dates require full git history at build time. On Vercel, set the `VERCEL_DEEP_CLONE=true` environment variable so builds clone the full history. Read [Last modified dates](/docs/configuration#last-modified-dates) for the full resolution order.
3708
3997
 
3709
3998
 
3999
+ ---
4000
+
4001
+ ---
4002
+ title: Steps
4003
+ description: Render numbered step-by-step instructions from Markdown headings or the Steps and Step components
4004
+ type: reference
4005
+ summary: Write consecutive headings that start with a number, such as "### 1. Install", to render a numbered step list. The Steps and Step components cover cases where a heading must be wrapped in another component.
4006
+ url: /docs/components/steps
4007
+ source: apps/template/content/docs/components/steps.mdx
4008
+ prerequisites:
4009
+ - /docs/syntax
4010
+ related:
4011
+ - /docs/syntax
4012
+ - /docs/table-of-contents
4013
+ ---
4014
+
4015
+ # Steps
4016
+
4017
+ Steps render sequential instructions as a numbered list with a counter beside each step heading. You write them as plain Markdown headings, so a page needs no imports and stays readable in Markdown output.
4018
+
4019
+ ## Write steps as numbered headings
4020
+
4021
+ Start each step heading with a number, a period, and a space. Consecutive headings at the same depth that follow this pattern become one step list.
4022
+
4023
+ ````md
4024
+ ## Deploy the project
4025
+
4026
+ ### 1. Install the CLI
4027
+
4028
+ Install the Vercel CLI globally.
4029
+
4030
+ ```bash
4031
+ pnpm add -g vercel
4032
+ ```
4033
+
4034
+ ### 2. Link the project
4035
+
4036
+ Run `vercel link` in the project directory and pick the team and project.
4037
+
4038
+ ### 3. Deploy
4039
+
4040
+ Run `vercel deploy` to create a preview deployment.
4041
+
4042
+ ## Next section
4043
+ ````
4044
+
4045
+ This renders as:
4046
+
4047
+ ### 1. Install the CLI
4048
+
4049
+ Install the Vercel CLI globally.
4050
+
4051
+ ```bash
4052
+ pnpm add -g vercel
4053
+ ```
4054
+
4055
+ ### 2. Link the project
4056
+
4057
+ Run `vercel link` in the project directory and pick the team and project.
4058
+
4059
+ ### 3. Deploy
4060
+
4061
+ Run `vercel deploy` to create a preview deployment.
4062
+
4063
+ ## How numbering and anchors work
4064
+
4065
+ Geistdocs removes the `1. ` prefix from the heading text at build time and draws the number with a CSS counter. As a result:
4066
+
4067
+ - The table of contents shows `Install the CLI`, not `1. Install the CLI`.
4068
+ - The heading anchor is `#install-the-cli`, so renumbering steps does not break links.
4069
+ - Custom anchors written as `### 1. Install the CLI [#install]` keep working.
4070
+ - Markdown routes and `llms.txt` output numbered headings, such as `### 1. Install the CLI`, which read naturally for agents.
4071
+
4072
+ The numbers you write are only used to detect steps. Geistdocs always counts from 1, so `### 4. Deploy` at the start of a list renders as step 1.
4073
+
4074
+ ## Rules for grouping steps
4075
+
4076
+ Geistdocs groups headings into a step list using these rules:
4077
+
4078
+ | Situation | Result |
4079
+ | --- | --- |
4080
+ | Consecutive numbered headings at the same depth | One step list |
4081
+ | A deeper heading inside a step, such as `#### Options` under `### 2. Configure` | Part of the current step |
4082
+ | A heading at the same or shallower depth without a number prefix | Ends the step list |
4083
+ | A numbered heading where inline code or a link immediately follows the number, such as `` ### 1. `vercel login` `` | Not detected as a step; move a word before the code, such as `` ### 1. Run `vercel login` `` |
4084
+
4085
+ Paragraphs, lists, code blocks, callouts, and images between two step headings belong to the earlier step.
4086
+
4087
+ ## Use the Steps and Step components
4088
+
4089
+ Use the components when a step heading has to be wrapped in another component, for example a framework switcher, and the heading pattern cannot be detected. Both components are in the default MDX component map and are exported from `@vercel/geistdocs/components/steps`.
4090
+
4091
+ ```mdx
4092
+ <Steps>
4093
+ <Step>
4094
+ ### Install the package
4095
+
4096
+ Run the install command for your package manager.
4097
+ </Step>
4098
+ <Step>
4099
+ ### Configure the project
4100
+
4101
+ Add the configuration file to the project root.
4102
+ </Step>
4103
+ </Steps>
4104
+ ```
4105
+
4106
+ This renders as:
4107
+
4108
+ <Steps>
4109
+ <Step>
4110
+ ### Install the package
4111
+
4112
+ Run the install command for your package manager.
4113
+ </Step>
4114
+ <Step>
4115
+ ### Configure the project
4116
+
4117
+ Add the configuration file to the project root.
4118
+ </Step>
4119
+ </Steps>
4120
+
4121
+ Do not add a number prefix to headings inside `Step`. The component draws the counter, and a prefix would create a nested step list.
4122
+
4123
+ ### Props
4124
+
4125
+ `Steps` and `Step` accept the standard `div` attributes. Both forward `className`, which is merged with the `fd-steps` and `fd-step` classes that carry the counter styling.
4126
+
4127
+ ## Markdown output
4128
+
4129
+ In `.md` routes and `llms.txt`, each step list becomes plain numbered headings, such as `### 1. Install the CLI`, followed by the step content. This applies to steps written as headings and to steps written with `Steps` and `Step`, so agents read the same sequence without the wrapper markup.
4130
+
4131
+
3710
4132
  ---
3711
4133
 
3712
4134
  ---
@@ -3767,6 +4189,46 @@ Use `####` when a sub-section needs its own breakdown. Geistdocs indents each le
3767
4189
 
3768
4190
  On mobile, Geistdocs replaces the sidebar outline with a compact menu in the page bar. The menu lists the same headings as a flat, indented list without the guide rail, so it stays legible on narrow screens.
3769
4191
 
4192
+ ## Hide the outline on a page
4193
+
4194
+ Set `tableOfContents: false` in the frontmatter to hide the outline on pages that do not benefit from it, such as overviews built from cards or short pages with one or two sections. The content then spans the column the outline would have used, so the page keeps the same right edge as every other page. Page actions and previous and next links stay in place.
4195
+
4196
+ ```yaml
4197
+ ---
4198
+ title: Overview
4199
+ tableOfContents: false
4200
+ ---
4201
+ ```
4202
+
4203
+ Frontmatter wins over the app-level `tableOfContent.enabled` option passed to `createDocsPage`. See [Hide the outline](/docs/guides/hidden-outline) for a page that sets `tableOfContents: false`.
4204
+
4205
+ ## Use the outline in custom pages
4206
+
4207
+ Routes you build in TSX inside the docs layout, such as a landing page, do not go through `createDocsPage`. Wrap their content in `GeistdocsPage` from `@vercel/geistdocs/page` to get the same layout and outline behavior as MDX pages. Pass `tableOfContents={false}` to hide the outline and let the content span its column.
4208
+
4209
+ ```tsx title="app/[lang]/docs/overview/page.tsx"
4210
+ import {
4211
+ GeistdocsPage,
4212
+ GeistdocsPageBody,
4213
+ GeistdocsPageDescription,
4214
+ GeistdocsPageTitle,
4215
+ } from "@vercel/geistdocs/page";
4216
+
4217
+ export default function OverviewPage() {
4218
+ return (
4219
+ <GeistdocsPage tableOfContents={false}>
4220
+ <GeistdocsPageTitle>Overview</GeistdocsPageTitle>
4221
+ <GeistdocsPageDescription>
4222
+ Start here to find the right guide.
4223
+ </GeistdocsPageDescription>
4224
+ <GeistdocsPageBody>{/* cards, links, or other content */}</GeistdocsPageBody>
4225
+ </GeistdocsPage>
4226
+ );
4227
+ }
4228
+ ```
4229
+
4230
+ The template includes this pattern at [/docs/custom-page](/docs/custom-page). `GeistdocsPage` accepts `toc` (outline items, usually the `toc` export of a compiled MDX page), `breadcrumb`, and `footer`. Pass an object to `tableOfContents` to add a `header` or `footer` around a visible outline. `GeistdocsPageBody` applies the prose styles that MDX content uses.
4231
+
3770
4232
  ## Write scannable headings
3771
4233
 
3772
4234
  Keep headings short and descriptive so the outline reads like a summary of the page. Name each heading after the goal of its section, and avoid stacking two headings with no content between them.