@vercel/geistdocs 1.25.1-canary.4e75e60 → 1.25.1-canary.62250e6

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 (86) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/components/code-block-tabs.js +1 -1
  3. package/dist/components/code-block.d.ts.map +1 -1
  4. package/dist/components/code-block.js +1 -1
  5. package/dist/components/copy-prompt.js +1 -1
  6. package/dist/components/image.d.ts +19 -0
  7. package/dist/components/image.d.ts.map +1 -0
  8. package/dist/components/image.js +9 -0
  9. package/dist/components/steps.d.ts +9 -0
  10. package/dist/components/steps.d.ts.map +1 -0
  11. package/dist/components/steps.js +9 -0
  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/message-metadata.d.ts.map +1 -1
  16. package/dist/internal/chat/message-metadata.js +15 -30
  17. package/dist/internal/chat/message-sources.d.ts +3 -0
  18. package/dist/internal/chat/message-sources.d.ts.map +1 -0
  19. package/dist/internal/chat/message-sources.js +23 -0
  20. package/dist/internal/chat/message.d.ts.map +1 -1
  21. package/dist/internal/chat/message.js +44 -10
  22. package/dist/internal/chat/shell.d.ts.map +1 -1
  23. package/dist/internal/chat/shell.js +7 -2
  24. package/dist/internal/chat/source-chunks.d.ts +9 -0
  25. package/dist/internal/chat/source-chunks.d.ts.map +1 -0
  26. package/dist/internal/chat/source-chunks.js +7 -0
  27. package/dist/internal/chat/sources.d.ts +1 -1
  28. package/dist/internal/chat/sources.d.ts.map +1 -1
  29. package/dist/internal/chat/sources.js +6 -3
  30. package/dist/internal/link-href.d.ts +13 -0
  31. package/dist/internal/link-href.d.ts.map +1 -0
  32. package/dist/internal/link-href.js +51 -0
  33. package/dist/internal/mdx-to-markdown.d.ts +3 -0
  34. package/dist/internal/mdx-to-markdown.d.ts.map +1 -0
  35. package/dist/internal/mdx-to-markdown.js +166 -0
  36. package/dist/internal/react-node-text.d.ts +4 -0
  37. package/dist/internal/react-node-text.d.ts.map +1 -0
  38. package/dist/internal/react-node-text.js +11 -0
  39. package/dist/internal/search.js +1 -1
  40. package/dist/internal/sidebar-tree.d.ts.map +1 -1
  41. package/dist/internal/sidebar-tree.js +6 -1
  42. package/dist/internal/toc-items.d.ts.map +1 -1
  43. package/dist/internal/toc-items.js +2 -1
  44. package/dist/mdx.d.ts.map +1 -1
  45. package/dist/mdx.js +5 -0
  46. package/dist/pages/docs.d.ts.map +1 -1
  47. package/dist/pages/docs.js +10 -5
  48. package/dist/routes/chat.d.ts.map +1 -1
  49. package/dist/routes/chat.js +30 -13
  50. package/dist/routes/llms.d.ts +1 -1
  51. package/dist/routes/llms.d.ts.map +1 -1
  52. package/dist/routes/llms.js +12 -2
  53. package/dist/source-config.d.ts +10 -0
  54. package/dist/source-config.d.ts.map +1 -1
  55. package/dist/source-config.js +20 -2
  56. package/dist/source.d.ts +10 -1
  57. package/dist/source.d.ts.map +1 -1
  58. package/dist/source.js +75 -34
  59. package/dist/versions.js +2 -2
  60. package/docs/agents.md +5 -3
  61. package/docs/llms.txt +388 -28
  62. package/docs/manifest.json +21 -3
  63. package/docs/pages/components/steps.md +129 -0
  64. package/docs/pages/deployment.md +30 -5
  65. package/docs/pages/getting-started.md +38 -12
  66. package/docs/pages/guides/nested-navigation.md +1 -1
  67. package/docs/pages/md.md +24 -5
  68. package/docs/pages/migration-2.md +106 -0
  69. package/docs/pages/migration.md +5 -2
  70. package/docs/pages/syntax.md +42 -0
  71. package/docs/sitemap.md +4 -2
  72. package/package.json +14 -4
  73. package/source-config.js +37 -2
  74. package/template/content/docs/components/meta.json +4 -0
  75. package/template/content/docs/components/steps.mdx +125 -0
  76. package/template/content/docs/deployment.mdx +31 -6
  77. package/template/content/docs/getting-started.mdx +39 -13
  78. package/template/content/docs/guides/nested-navigation.mdx +1 -1
  79. package/template/content/docs/md.mdx +24 -5
  80. package/template/content/docs/meta.json +3 -0
  81. package/template/content/docs/migration-2.mdx +106 -0
  82. package/template/content/docs/migration.mdx +5 -1
  83. package/template/content/docs/syntax.mdx +42 -0
  84. package/template/next.config.ts +9 -0
  85. package/template/package.json +3 -3
  86. package/theme.css +50 -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.4e75e60.
3
+ These docs are bundled with `@vercel/geistdocs` 1.25.1-canary.62250e6.
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.
@@ -25,6 +26,7 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
25
26
  - [llms.txt](pages/llms-txt.md): A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
26
27
  - [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
28
  - [RSS](pages/rss.md): An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
29
+ - [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
30
  - [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
31
 
30
32
  ---
@@ -148,39 +150,47 @@ related:
148
150
 
149
151
  # Getting Started
150
152
 
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.
153
+ 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
154
 
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`.
155
+ 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
156
 
155
157
  ## Prerequisites
156
158
 
157
159
  Before you begin, install:
158
160
 
159
- - Node.js 18 or later
160
- - pnpm, npm, or another package manager
161
+ - Node.js 20.9 or later
162
+ - pnpm
161
163
  - Git
162
164
 
163
- ## Create a project
165
+ The CLI always uses pnpm to install the generated project's dependencies.
164
166
 
165
- Run the Geistdocs CLI from an empty parent folder:
167
+ ## Authenticate package access
166
168
 
167
- ```bash title="Terminal"
168
- pnpm dlx @vercel/geistdocs init --name my-docs
169
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Configure your user-level `~/.npmrc` before running the CLI:
170
+
171
+ ```ini title="~/.npmrc"
172
+ @vercel:registry=https://registry.npmjs.org/
173
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
174
+ always-auth=true
169
175
  ```
170
176
 
171
- You can also use npm:
177
+ 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.
178
+
179
+ ## Create a project
180
+
181
+ Run the Geistdocs CLI from an empty parent folder:
172
182
 
173
183
  ```bash title="Terminal"
174
- npx @vercel/geistdocs init --name my-docs
184
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
175
185
  ```
176
186
 
177
187
  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
188
 
179
189
  ## Understand generated dependencies
180
190
 
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.
191
+ 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
192
 
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.
193
+ Keep those integrations package-backed. Update Geistdocs instead of copying package internals into the app.
184
194
 
185
195
  ## Start the development server
186
196
 
@@ -193,6 +203,14 @@ pnpm dev
193
203
 
194
204
  Open `http://localhost:3000` in your browser.
195
205
 
206
+ Start with these files:
207
+
208
+ - `geistdocs.tsx` for the site title, logo, navigation, repository, and AI prompt.
209
+ - `content/docs/index.mdx` for the documentation overview.
210
+ - `content/docs/meta.json` for sidebar order and groups.
211
+
212
+ Only customize `components/geistdocs/*`, `lib/geistdocs/*`, or route adapters when the generated defaults do not fit your site.
213
+
196
214
  ## Edit your first page
197
215
 
198
216
  Docs live in `content/docs`. Edit the overview page:
@@ -251,6 +269,16 @@ pnpm exec geistdocs update
251
269
 
252
270
  Review and test dependency changes before committing.
253
271
 
272
+ ## Verify and deploy
273
+
274
+ Run a production build before publishing:
275
+
276
+ ```bash title="Terminal"
277
+ pnpm build
278
+ ```
279
+
280
+ Then follow [Deploy to Vercel](/docs/deployment), including private package access and environment-variable setup.
281
+
254
282
 
255
283
  ---
256
284
 
@@ -324,7 +352,7 @@ Set this variable explicitly when deploying outside Vercel. Use a hostname such
324
352
  title: Deploy to Vercel
325
353
  description: Learn how to deploy your Geistdocs site to Vercel
326
354
  type: guide
327
- summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
355
+ summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
328
356
  url: /docs/deployment
329
357
  source: apps/template/content/docs/deployment.mdx
330
358
  prerequisites:
@@ -336,9 +364,9 @@ related:
336
364
 
337
365
  # Deploy to Vercel
338
366
 
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.
367
+ Deploy a Geistdocs site to Vercel as a Next.js app. Configure private package access, environment variables, and the production URL before shipping.
340
368
 
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.
369
+ 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
370
 
343
371
  ## Prerequisites
344
372
 
@@ -348,6 +376,31 @@ Before deploying, you need:
348
376
  - A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
349
377
  - Your Vercel account connected to your GitHub account
350
378
  - Environment variables ready (see [Environment Variables](/docs/env))
379
+ - Access to the restricted `@vercel` npm packages
380
+
381
+ ## Configure private package access
382
+
383
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Package installation fails without npm authentication.
384
+
385
+ 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.
386
+
387
+ For GitHub Actions, ask `#help-it` to allow the repository to use the `NPM_TOKEN` organization secret, then pass it to the install step:
388
+
389
+ ```yaml title=".github/workflows/check.yml"
390
+ - uses: pnpm/action-setup@v4
391
+
392
+ - uses: actions/setup-node@v4
393
+ with:
394
+ node-version: 20
395
+ cache: pnpm
396
+ registry-url: https://registry.npmjs.org
397
+
398
+ - run: pnpm install
399
+ env:
400
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
401
+ ```
402
+
403
+ 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
404
 
352
405
  ## Deploy to Vercel
353
406
 
@@ -357,9 +410,9 @@ To deploy from the Vercel dashboard:
357
410
  2. Select your Geistdocs repository
358
411
  3. Configure your project settings:
359
412
  - **Framework Preset**: Next.js (automatically detected)
360
- - **Build Command**: `pnpm build` or `npm run build`
413
+ - **Build Command**: `pnpm build`
361
414
  - **Output Directory**: `.next` (default)
362
- - **Install Command**: `pnpm install` or `npm install`
415
+ - **Install Command**: `pnpm install`
363
416
  4. Add your environment variables (see [Environment Variables](/docs/env))
364
417
  5. Click "Deploy"
365
418
 
@@ -378,7 +431,7 @@ The Geistdocs site does not need Vertex credentials. The platform proxy authenti
378
431
  ---
379
432
 
380
433
  ---
381
- title: Migration guide
434
+ title: Migrate to Geistdocs
382
435
  description: Migrate a Fumadocs or custom Geist docs site to package-backed Geistdocs
383
436
  type: guide
384
437
  summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
@@ -393,10 +446,13 @@ related:
393
446
  - /docs/agent-readiness
394
447
  ---
395
448
 
396
- # Migration guide
449
+ # Migrate to Geistdocs
397
450
 
398
451
  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
452
 
453
+ > Note:
454
+ 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.
455
+
400
456
  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
457
 
402
458
  ## Before you migrate
@@ -804,6 +860,116 @@ Check these URLs locally:
804
860
  - Read [Agent readiness](/docs/agent-readiness) to configure `/agents.md` and `/.well-known/mcp.json` for AI agents.
805
861
 
806
862
 
863
+ ---
864
+
865
+ ---
866
+ title: Migrate from Geistdocs 1.x to 2.0
867
+ description: Upgrade imports, dependencies, and routing without copying Geistdocs internals
868
+ type: guide
869
+ summary: A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.
870
+ url: /docs/migration-2
871
+ source: apps/template/content/docs/migration-2.mdx
872
+ related:
873
+ - /docs/migration
874
+ - /docs/configuration
875
+ - /docs/versioned-docs
876
+ - /docs/proxy
877
+ ---
878
+
879
+ # Migrate from Geistdocs 1.x to 2.0
880
+
881
+ 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.
882
+
883
+ 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.
884
+
885
+ ## 1. Upgrade dependencies
886
+
887
+ ```bash title="Terminal"
888
+ 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
889
+ ```
890
+
891
+ 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.
892
+
893
+ ## 2. Replace removed imports
894
+
895
+ | Geistdocs 1.x import | Geistdocs 2.0 replacement |
896
+ | --- | --- |
897
+ | `badge`, `button`, `dialog`, `drawer`, `input`, `kbd`, `separator`, `sheet`, `spinner`, `textarea`, `theme-switcher`, or `tooltip` | Import the matching component from `@vercel/geistcn/components/<name>`. |
898
+ | `switch` | Use `@vercel/geistcn/components/toggle`. |
899
+ | `sonner` | Use `Toasts` and `useToasts` from `@vercel/geistcn/components/toasts`. |
900
+ | `theme-aware-image` | Use Geistcn `Image` with `srcLight` and `srcDark`. |
901
+ | `button-group`, `card`, or `input-group` | Choose a Geistcn component or keep an app-owned composition; there is no API-compatible replacement. |
902
+ | `@vercel/geistdocs/assets/icons` or `assets/icons/*` | `@vercel/geistcn-assets/icons` or `icons/*` |
903
+ | `@vercel/geistdocs/assets/logos` or `assets/logos/*` | `@vercel/geistcn-assets/logos` or `logos/*` |
904
+
905
+ Keep documentation-specific imports such as `callout`, `code-block`, `code-block-tabs`, `collapsible`, `command-prompt`, `copy-prompt`, `mermaid`, and `video` on `@vercel/geistdocs/components/*`.
906
+
907
+ Import the package stylesheet once and apply the Geist font classes at the root:
908
+
909
+ ```tsx title="app/[lang]/layout.tsx"
910
+ import "@vercel/geistdocs/styles.css";
911
+ import { geistFontClasses } from "@vercel/geistcn/core";
912
+
913
+ export default function RootLayout({ children }: LayoutProps<"/[lang]">) {
914
+ return (
915
+ <html className={geistFontClasses}>
916
+ <body>{children}</body>
917
+ </html>
918
+ );
919
+ }
920
+ ```
921
+
922
+ ## 3. Use the Next.js and source integrations
923
+
924
+ ```ts title="next.config.ts"
925
+ import { createGeistdocs } from "@vercel/geistdocs/next";
926
+ import type { NextConfig } from "next";
927
+
928
+ const config: NextConfig = {
929
+ modularizeImports: {
930
+ "@vercel/geistcn/components": {
931
+ skipDefaultConversion: true,
932
+ transform: "@vercel/geistcn/components/{{ kebabCase member }}",
933
+ },
934
+ "@vercel/geistcn/core": {
935
+ skipDefaultConversion: true,
936
+ transform: "@vercel/geistcn/core",
937
+ },
938
+ },
939
+ transpilePackages: [
940
+ "@vercel/geistcn",
941
+ "@vercel/geist-test-utils",
942
+ "@vercel/next-themes",
943
+ ],
944
+ cacheComponents: true,
945
+ partialPrefetching: true,
946
+ };
947
+
948
+ export default createGeistdocs()(config);
949
+ ```
950
+
951
+ 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.
952
+
953
+ ## 4. Preserve routing invariants
954
+
955
+ - If Next.js uses `basePath`, set the same value in Geistdocs config.
956
+ - 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.
957
+ - For versioned docs, use `createVersionedSources` and pass server-computed `collectVersionSwitchPaths` to the version selector so missing pages fall back to an existing ancestor.
958
+ - 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.
959
+ - Keep product-specific navigation titles, badges, related links, and content transforms in the app.
960
+
961
+ ## 5. Verify the upgrade
962
+
963
+ - Run install, typecheck, tests, and a production build.
964
+ - Open representative HTML pages and their `.md` equivalents, including a not-found path.
965
+ - Test search, Ask AI citations, proxy rewrites, and agent-readable routes.
966
+ - Switch versions from pages that do and do not exist in the target version.
967
+ - Confirm links do not trigger broad post-load prefetching and Ask AI is not eagerly loaded.
968
+ - Recheck LCP, CLS, accessibility, and post-render network and CPU activity.
969
+
970
+ For a first migration from Fumadocs or a custom docs site, follow the [full migration guide](/docs/migration).
971
+
972
+
807
973
  ---
808
974
 
809
975
  ---
@@ -1274,6 +1440,10 @@ Create ordered lists with numbers:
1274
1440
  2. Second step
1275
1441
  3. Third step
1276
1442
 
1443
+ ### Steps
1444
+
1445
+ 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.
1446
+
1277
1447
  ### Blockquotes
1278
1448
 
1279
1449
  Use `>` to create blockquotes:
@@ -1398,6 +1568,44 @@ Add images with `![alt text](url)`:
1398
1568
  ![Description of the image](/path/to/image.png)
1399
1569
  ```
1400
1570
 
1571
+ Use `<Image>` when an image needs the standard documentation presentation and
1572
+ an optional description. It uses Geistcn's image component without a lightbox
1573
+ or other interaction:
1574
+
1575
+ ```mdx
1576
+ <Image
1577
+ alt="Deployment graph"
1578
+ caption="Requests move from the edge to the selected region."
1579
+ height={480}
1580
+ src="/deployment-graph.png"
1581
+ width={800}
1582
+ />
1583
+ ```
1584
+
1585
+ This renders as:
1586
+
1587
+ <Image
1588
+ alt="Navigation Inspector showing a loading shell for a page load"
1589
+ caption="The Navigation Inspector paused on a page load."
1590
+ height={389}
1591
+ srcDark="https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/dark/inspector-load.png"
1592
+ srcLight="https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/light/inspector-load.png"
1593
+ width={472}
1594
+ />
1595
+
1596
+ For theme-aware images, provide both sources:
1597
+
1598
+ ```mdx
1599
+ <Image
1600
+ alt="Deployment graph"
1601
+ caption="Requests move from the edge to the selected region."
1602
+ height={480}
1603
+ srcDark="/deployment-graph-dark.png"
1604
+ srcLight="/deployment-graph-light.png"
1605
+ width={800}
1606
+ />
1607
+ ```
1608
+
1401
1609
  ## GitHub Flavored Markdown
1402
1610
 
1403
1611
  Geistdocs supports GFM extensions including tables, task lists, and autolinks.
@@ -2443,7 +2651,7 @@ related:
2443
2651
 
2444
2652
  # .md Extension
2445
2653
 
2446
- 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.
2654
+ 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.
2447
2655
 
2448
2656
  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.
2449
2657
 
@@ -2463,8 +2671,8 @@ https://yourdomain.com/docs/getting-started.mdx
2463
2671
 
2464
2672
  The `.mdx` version returns:
2465
2673
 
2466
- - The page title as an H1 heading
2467
- - The full processed Markdown content
2674
+ - Frontmatter with the canonical page URL, docs index, and last-updated date when available
2675
+ - The full page content as plain Markdown
2468
2676
  - No HTML, styling, or navigation
2469
2677
 
2470
2678
  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`.
@@ -2513,11 +2721,30 @@ The response includes:
2513
2721
 
2514
2722
  - Content-Type: `text/markdown`
2515
2723
  - `Link: <canonical page URL>; rel="canonical"` for resolved pages
2516
- - The page title as a level 1 heading
2517
- - Processed Markdown content from Fumadocs
2724
+ - Frontmatter with page metadata and discovery links
2725
+ - Page content with presentation-only MDX components removed
2518
2726
 
2519
2727
  All MDX components are processed and converted to plain Markdown equivalents.
2520
2728
 
2729
+ ### Customize frontmatter
2730
+
2731
+ 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:
2732
+
2733
+ ```ts title="lib/geistdocs/source.ts"
2734
+ export const geistdocsSource = createSource({
2735
+ config,
2736
+ docs,
2737
+ markdown: {
2738
+ frontmatter: (defaults) => ({
2739
+ docs_index: "/docs/llms.txt",
2740
+ version: "16.3.4",
2741
+ }),
2742
+ },
2743
+ });
2744
+ ```
2745
+
2746
+ The callback returns only additions and overrides; Geistdocs keeps the remaining generated fields from `defaults`.
2747
+
2521
2748
  ## Missing documentation pages
2522
2749
 
2523
2750
  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.
@@ -3121,7 +3348,7 @@ Geistdocs applies a color for each method:
3121
3348
  | `PUT`, `PATCH` | Amber |
3122
3349
  | `DEL`, `DELETE` | Red |
3123
3350
 
3124
- 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.
3351
+ 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.
3125
3352
 
3126
3353
  ## Add links to the navigation
3127
3354
 
@@ -3733,6 +3960,139 @@ lastModified: 2025-11-12
3733
3960
  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.
3734
3961
 
3735
3962
 
3963
+ ---
3964
+
3965
+ ---
3966
+ title: Steps
3967
+ description: Render numbered step-by-step instructions from Markdown headings or the Steps and Step components
3968
+ type: reference
3969
+ 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.
3970
+ url: /docs/components/steps
3971
+ source: apps/template/content/docs/components/steps.mdx
3972
+ prerequisites:
3973
+ - /docs/syntax
3974
+ related:
3975
+ - /docs/syntax
3976
+ - /docs/table-of-contents
3977
+ ---
3978
+
3979
+ # Steps
3980
+
3981
+ 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.
3982
+
3983
+ ## Write steps as numbered headings
3984
+
3985
+ 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.
3986
+
3987
+ ````md
3988
+ ## Deploy the project
3989
+
3990
+ ### 1. Install the CLI
3991
+
3992
+ Install the Vercel CLI globally.
3993
+
3994
+ ```bash
3995
+ pnpm add -g vercel
3996
+ ```
3997
+
3998
+ ### 2. Link the project
3999
+
4000
+ Run `vercel link` in the project directory and pick the team and project.
4001
+
4002
+ ### 3. Deploy
4003
+
4004
+ Run `vercel deploy` to create a preview deployment.
4005
+
4006
+ ## Next section
4007
+ ````
4008
+
4009
+ This renders as:
4010
+
4011
+ ### 1. Install the CLI
4012
+
4013
+ Install the Vercel CLI globally.
4014
+
4015
+ ```bash
4016
+ pnpm add -g vercel
4017
+ ```
4018
+
4019
+ ### 2. Link the project
4020
+
4021
+ Run `vercel link` in the project directory and pick the team and project.
4022
+
4023
+ ### 3. Deploy
4024
+
4025
+ Run `vercel deploy` to create a preview deployment.
4026
+
4027
+ ## How numbering and anchors work
4028
+
4029
+ Geistdocs removes the `1. ` prefix from the heading text at build time and draws the number with a CSS counter. As a result:
4030
+
4031
+ - The table of contents shows `Install the CLI`, not `1. Install the CLI`.
4032
+ - The heading anchor is `#install-the-cli`, so renumbering steps does not break links.
4033
+ - Custom anchors written as `### 1. Install the CLI [#install]` keep working.
4034
+ - Markdown routes and `llms.txt` output numbered headings, such as `### 1. Install the CLI`, which read naturally for agents.
4035
+
4036
+ 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.
4037
+
4038
+ ## Rules for grouping steps
4039
+
4040
+ Geistdocs groups headings into a step list using these rules:
4041
+
4042
+ | Situation | Result |
4043
+ | --- | --- |
4044
+ | Consecutive numbered headings at the same depth | One step list |
4045
+ | A deeper heading inside a step, such as `#### Options` under `### 2. Configure` | Part of the current step |
4046
+ | A heading at the same or shallower depth without a number prefix | Ends the step list |
4047
+ | 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` `` |
4048
+
4049
+ Paragraphs, lists, code blocks, callouts, and images between two step headings belong to the earlier step.
4050
+
4051
+ ## Use the Steps and Step components
4052
+
4053
+ 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`.
4054
+
4055
+ ```mdx
4056
+ <Steps>
4057
+ <Step>
4058
+ ### Install the package
4059
+
4060
+ Run the install command for your package manager.
4061
+ </Step>
4062
+ <Step>
4063
+ ### Configure the project
4064
+
4065
+ Add the configuration file to the project root.
4066
+ </Step>
4067
+ </Steps>
4068
+ ```
4069
+
4070
+ This renders as:
4071
+
4072
+ <Steps>
4073
+ <Step>
4074
+ ### Install the package
4075
+
4076
+ Run the install command for your package manager.
4077
+ </Step>
4078
+ <Step>
4079
+ ### Configure the project
4080
+
4081
+ Add the configuration file to the project root.
4082
+ </Step>
4083
+ </Steps>
4084
+
4085
+ Do not add a number prefix to headings inside `Step`. The component draws the counter, and a prefix would create a nested step list.
4086
+
4087
+ ### Props
4088
+
4089
+ `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.
4090
+
4091
+ ## Markdown output
4092
+
4093
+ 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.
4094
+
4095
+
3736
4096
  ---
3737
4097
 
3738
4098
  ---
@@ -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",
@@ -188,6 +197,15 @@
188
197
  "type": "conceptual",
189
198
  "url": "/docs/rss"
190
199
  },
200
+ {
201
+ "description": "Render numbered step-by-step instructions from Markdown headings or the Steps and Step components",
202
+ "path": "pages/components/steps.md",
203
+ "source": "apps/template/content/docs/components/steps.mdx",
204
+ "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.",
205
+ "title": "Steps",
206
+ "type": "reference",
207
+ "url": "/docs/components/steps"
208
+ },
191
209
  {
192
210
  "description": "Show an \"On this page\" outline that tracks the reader's position along a straight guide rail",
193
211
  "path": "pages/table-of-contents.md",
@@ -199,5 +217,5 @@
199
217
  }
200
218
  ],
201
219
  "source": "apps/template/content/docs",
202
- "version": "1.25.1-canary.4e75e60"
220
+ "version": "1.25.1-canary.62250e6"
203
221
  }