@vercel/geistdocs 1.25.1-canary.c58830e → 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 (138) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/components/blockquote.js +1 -1
  3. package/dist/components/callout.d.ts +13 -10
  4. package/dist/components/callout.d.ts.map +1 -1
  5. package/dist/components/callout.js +6 -6
  6. package/dist/components/code-block-tabs.d.ts.map +1 -1
  7. package/dist/components/code-block-tabs.js +3 -1
  8. package/dist/components/code-block.d.ts.map +1 -1
  9. package/dist/components/code-block.js +1 -1
  10. package/dist/components/command-prompt.d.ts.map +1 -1
  11. package/dist/components/command-prompt.js +15 -22
  12. package/dist/components/copy-prompt.d.ts +2 -1
  13. package/dist/components/copy-prompt.d.ts.map +1 -1
  14. package/dist/components/copy-prompt.js +2 -2
  15. package/dist/components/heading.d.ts +7 -0
  16. package/dist/components/heading.d.ts.map +1 -0
  17. package/dist/components/heading.js +14 -0
  18. package/dist/components/image.d.ts +19 -0
  19. package/dist/components/image.d.ts.map +1 -0
  20. package/dist/components/image.js +9 -0
  21. package/dist/components/table.d.ts +3 -0
  22. package/dist/components/table.d.ts.map +1 -0
  23. package/dist/components/table.js +3 -0
  24. package/dist/controls.d.ts.map +1 -1
  25. package/dist/controls.js +4 -3
  26. package/dist/internal/chat/activity.d.ts +20 -0
  27. package/dist/internal/chat/activity.d.ts.map +1 -0
  28. package/dist/internal/chat/activity.js +43 -0
  29. package/dist/internal/chat/context.d.ts +2 -0
  30. package/dist/internal/chat/context.d.ts.map +1 -1
  31. package/dist/internal/chat/context.js +24 -3
  32. package/dist/internal/chat/dots-spinner.d.ts.map +1 -1
  33. package/dist/internal/chat/dots-spinner.js +15 -9
  34. package/dist/internal/chat/loading-skeleton.d.ts +7 -0
  35. package/dist/internal/chat/loading-skeleton.d.ts.map +1 -0
  36. package/dist/internal/chat/loading-skeleton.js +46 -0
  37. package/dist/internal/chat/message-metadata.d.ts.map +1 -1
  38. package/dist/internal/chat/message-metadata.js +15 -30
  39. package/dist/internal/chat/message-sources.d.ts +3 -0
  40. package/dist/internal/chat/message-sources.d.ts.map +1 -0
  41. package/dist/internal/chat/message-sources.js +23 -0
  42. package/dist/internal/chat/message.d.ts.map +1 -1
  43. package/dist/internal/chat/message.js +59 -5
  44. package/dist/internal/chat/shell.d.ts.map +1 -1
  45. package/dist/internal/chat/shell.js +17 -17
  46. package/dist/internal/chat/source-chunks.d.ts +9 -0
  47. package/dist/internal/chat/source-chunks.d.ts.map +1 -0
  48. package/dist/internal/chat/source-chunks.js +7 -0
  49. package/dist/internal/chat/sources.d.ts +1 -1
  50. package/dist/internal/chat/sources.d.ts.map +1 -1
  51. package/dist/internal/chat/sources.js +7 -1
  52. package/dist/internal/link-href.d.ts +13 -0
  53. package/dist/internal/link-href.d.ts.map +1 -0
  54. package/dist/internal/link-href.js +51 -0
  55. package/dist/internal/mdx-to-markdown.d.ts +3 -0
  56. package/dist/internal/mdx-to-markdown.d.ts.map +1 -0
  57. package/dist/internal/mdx-to-markdown.js +134 -0
  58. package/dist/internal/mousedown-navigation-utils.d.ts +5 -0
  59. package/dist/internal/mousedown-navigation-utils.d.ts.map +1 -0
  60. package/dist/internal/mousedown-navigation-utils.js +95 -0
  61. package/dist/internal/mousedown-navigation.d.ts +10 -0
  62. package/dist/internal/mousedown-navigation.d.ts.map +1 -0
  63. package/dist/internal/mousedown-navigation.js +42 -0
  64. package/dist/internal/navbar/desktop-menu.js +1 -1
  65. package/dist/internal/navbar/mobile-menu.d.ts.map +1 -1
  66. package/dist/internal/navbar/mobile-menu.js +8 -13
  67. package/dist/internal/navbar/navbar-shell.d.ts.map +1 -1
  68. package/dist/internal/navbar/navbar-shell.js +2 -1
  69. package/dist/internal/page-actions-client.d.ts.map +1 -1
  70. package/dist/internal/page-actions-client.js +36 -32
  71. package/dist/internal/provider-client.d.ts.map +1 -1
  72. package/dist/internal/provider-client.js +29 -5
  73. package/dist/internal/react-node-text.d.ts +4 -0
  74. package/dist/internal/react-node-text.d.ts.map +1 -0
  75. package/dist/internal/react-node-text.js +11 -0
  76. package/dist/internal/search.d.ts.map +1 -1
  77. package/dist/internal/search.js +1 -1
  78. package/dist/internal/sidebar-responsive.d.ts +0 -1
  79. package/dist/internal/sidebar-responsive.d.ts.map +1 -1
  80. package/dist/internal/sidebar-responsive.js +0 -9
  81. package/dist/internal/sidebar-tree.d.ts.map +1 -1
  82. package/dist/internal/sidebar-tree.js +6 -1
  83. package/dist/internal/sidebar.d.ts.map +1 -1
  84. package/dist/internal/sidebar.js +78 -49
  85. package/dist/internal/table-of-contents.d.ts.map +1 -1
  86. package/dist/internal/table-of-contents.js +1 -1
  87. package/dist/internal/toc-items.d.ts.map +1 -1
  88. package/dist/internal/toc-items.js +18 -7
  89. package/dist/internal/ui/dropdown-menu.js +6 -6
  90. package/dist/internal/ui/navigation-menu.js +2 -2
  91. package/dist/internal/use-mobile.d.ts.map +1 -1
  92. package/dist/internal/use-mobile.js +2 -12
  93. package/dist/layout.d.ts +1 -0
  94. package/dist/layout.d.ts.map +1 -1
  95. package/dist/layout.js +2 -0
  96. package/dist/mdx.d.ts.map +1 -1
  97. package/dist/mdx.js +13 -4
  98. package/dist/pages/docs.d.ts.map +1 -1
  99. package/dist/pages/docs.js +17 -9
  100. package/dist/routes/chat.d.ts +1 -1
  101. package/dist/routes/chat.d.ts.map +1 -1
  102. package/dist/routes/chat.js +31 -14
  103. package/dist/routes/llms.d.ts +1 -1
  104. package/dist/routes/llms.d.ts.map +1 -1
  105. package/dist/routes/llms.js +12 -2
  106. package/dist/source.d.ts +10 -1
  107. package/dist/source.d.ts.map +1 -1
  108. package/dist/source.js +75 -34
  109. package/dist/versions.js +2 -2
  110. package/docs/agents.md +4 -3
  111. package/docs/llms.txt +359 -39
  112. package/docs/manifest.json +12 -3
  113. package/docs/pages/ask-ai.md +2 -2
  114. package/docs/pages/deployment.md +30 -5
  115. package/docs/pages/getting-started.md +38 -12
  116. package/docs/pages/guides/nested-navigation.md +1 -1
  117. package/docs/pages/md.md +25 -6
  118. package/docs/pages/migration-2.md +106 -0
  119. package/docs/pages/migration.md +5 -2
  120. package/docs/pages/syntax.md +144 -8
  121. package/docs/sitemap.md +3 -2
  122. package/package.json +12 -5
  123. package/template/app/[lang]/layout.tsx +4 -0
  124. package/template/app/styles/geistdocs.css +1 -1
  125. package/template/components/ui/button.tsx +1 -1
  126. package/template/content/docs/ask-ai.cn.mdx +2 -2
  127. package/template/content/docs/ask-ai.mdx +2 -2
  128. package/template/content/docs/deployment.mdx +31 -6
  129. package/template/content/docs/getting-started.mdx +39 -13
  130. package/template/content/docs/guides/nested-navigation.mdx +1 -1
  131. package/template/content/docs/md.mdx +25 -6
  132. package/template/content/docs/meta.json +1 -0
  133. package/template/content/docs/migration-2.mdx +106 -0
  134. package/template/content/docs/migration.mdx +5 -1
  135. package/template/content/docs/syntax.mdx +150 -8
  136. package/template/next.config.ts +9 -0
  137. package/template/package.json +4 -4
  138. package/theme.css +39 -105
@@ -2,7 +2,7 @@
2
2
  title: Deploy to Vercel
3
3
  description: Learn how to deploy your Geistdocs site to Vercel
4
4
  type: guide
5
- summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
5
+ summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
6
6
  url: /docs/deployment
7
7
  source: apps/template/content/docs/deployment.mdx
8
8
  prerequisites:
@@ -14,9 +14,9 @@ related:
14
14
 
15
15
  # Deploy to Vercel
16
16
 
17
- Deploy a Geistdocs site to Vercel as a Next.js app. Make sure your package dependency, environment variables, and production URL are configured before shipping.
17
+ Deploy a Geistdocs site to Vercel as a Next.js app. Configure private package access, environment variables, and the production URL before shipping.
18
18
 
19
- Help me deploy this Geistdocs project to Vercel. Check the package scripts, required environment variables, and Vercel project settings, then give me a deploy checklist for production.
19
+ Help me deploy this Geistdocs 2.0 project to Vercel. Verify private npm access for its Geistcn dependencies, then review the package scripts, environment variables, GitHub Actions authentication, and Vercel project settings.
20
20
 
21
21
  ## Prerequisites
22
22
 
@@ -26,6 +26,31 @@ Before deploying, you need:
26
26
  - A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
27
27
  - Your Vercel account connected to your GitHub account
28
28
  - Environment variables ready (see [Environment Variables](/docs/env))
29
+ - Access to the restricted `@vercel` npm packages
30
+
31
+ ## Configure private package access
32
+
33
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Package installation fails without npm authentication.
34
+
35
+ For a Vercel deployment, ask `#help-core-platform` to add your Vercel project to the shared `NPM_TOKEN` environment variable list. Include the project link and required environments. Do not copy the shared token into the repository or project documentation.
36
+
37
+ For GitHub Actions, ask `#help-it` to allow the repository to use the `NPM_TOKEN` organization secret, then pass it to the install step:
38
+
39
+ ```yaml title=".github/workflows/check.yml"
40
+ - uses: pnpm/action-setup@v4
41
+
42
+ - uses: actions/setup-node@v4
43
+ with:
44
+ node-version: 20
45
+ cache: pnpm
46
+ registry-url: https://registry.npmjs.org
47
+
48
+ - run: pnpm install
49
+ env:
50
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
51
+ ```
52
+
53
+ Read [How do I use private dependencies with Vercel?](https://vercel.com/kb/guide/using-private-dependencies-with-vercel) for the platform authentication behavior.
29
54
 
30
55
  ## Deploy to Vercel
31
56
 
@@ -35,9 +60,9 @@ To deploy from the Vercel dashboard:
35
60
  2. Select your Geistdocs repository
36
61
  3. Configure your project settings:
37
62
  - **Framework Preset**: Next.js (automatically detected)
38
- - **Build Command**: `pnpm build` or `npm run build`
63
+ - **Build Command**: `pnpm build`
39
64
  - **Output Directory**: `.next` (default)
40
- - **Install Command**: `pnpm install` or `npm install`
65
+ - **Install Command**: `pnpm install`
41
66
  4. Add your environment variables (see [Environment Variables](/docs/env))
42
67
  5. Click "Deploy"
43
68
 
@@ -14,39 +14,47 @@ related:
14
14
 
15
15
  # Getting Started
16
16
 
17
- Create a Geistdocs site with the package CLI, then edit the generated content and configuration files. If you already have a Fumadocs or custom Geist docs site, read [Migration guide](/docs/migration) before moving route adapters and middleware behavior.
17
+ Create a new Geistdocs 2.0 site with the package CLI, then customize its identity, content, and navigation. If you already have a documentation site, use [Migrate to Geistdocs](/docs/migration) or [Migrate 1.x → 2.0](/docs/migration-2) instead.
18
18
 
19
- Create a Geistdocs project with `pnpm dlx @vercel/geistdocs init --name my-docs`. Then open `my-docs`, run `pnpm dev`, and explain which files I should edit first: `geistdocs.tsx`, `content/docs`, `content/docs/meta.json`, and `components/geistdocs/mdx-components.tsx`.
19
+ Create a new Geistdocs project with `pnpm dlx @vercel/geistdocs@latest init --name my-docs`. Confirm the prerequisites, run `pnpm dev`, and help me customize `geistdocs.tsx`, `content/docs/index.mdx`, and `content/docs/meta.json`. Keep the generated integrations package-backed.
20
20
 
21
21
  ## Prerequisites
22
22
 
23
23
  Before you begin, install:
24
24
 
25
- - Node.js 18 or later
26
- - pnpm, npm, or another package manager
25
+ - Node.js 20.9 or later
26
+ - pnpm
27
27
  - Git
28
28
 
29
- ## Create a project
29
+ The CLI always uses pnpm to install the generated project's dependencies.
30
30
 
31
- Run the Geistdocs CLI from an empty parent folder:
31
+ ## Authenticate package access
32
32
 
33
- ```bash title="Terminal"
34
- pnpm dlx @vercel/geistdocs init --name my-docs
33
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Configure your user-level `~/.npmrc` before running the CLI:
34
+
35
+ ```ini title="~/.npmrc"
36
+ @vercel:registry=https://registry.npmjs.org/
37
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
38
+ always-auth=true
35
39
  ```
36
40
 
37
- You can also use npm:
41
+ Set `NPM_TOKEN` from an approved internal source. Never put the token value in `.npmrc`, an `.env` file, shell history, or Git. See [Deploy to Vercel](/docs/deployment#configure-private-package-access) for automated installs.
42
+
43
+ ## Create a project
44
+
45
+ Run the Geistdocs CLI from an empty parent folder:
38
46
 
39
47
  ```bash title="Terminal"
40
- npx @vercel/geistdocs init --name my-docs
48
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
41
49
  ```
42
50
 
43
51
  The CLI copies the template bundled in the package, rewrites the generated app to depend on the same `@vercel/geistdocs` version, installs dependencies, copies `.env.example` to `.env.local`, and initializes Git.
44
52
 
45
53
  ## Understand generated dependencies
46
54
 
47
- Generated projects include `@vercel/geistdocs`, `ai` v6, and `@ai-sdk/react` v3. Geistdocs uses those AI SDK packages for Ask AI, including the chat client transport and `createChatRoute` server behavior.
55
+ Generated projects pin the resolved `@vercel/geistdocs` version and include its matching Geistcn dependencies, AI SDK v6, and `@ai-sdk/react` v3. The template already configures styles, fonts, Cache Components, Partial Prefetching, source adapters, search, Ask AI, and agent-readable routes.
48
56
 
49
- Update Ask AI by updating `@vercel/geistdocs`, not by copying package chat internals into the app. If your project uses the AI SDK directly for separate product features, keep that code compatible with the app's installed AI SDK version; package-owned Ask AI does not need to match another consumer project's `ai` version.
57
+ Keep those integrations package-backed. Update Geistdocs instead of copying package internals into the app.
50
58
 
51
59
  ## Start the development server
52
60
 
@@ -59,6 +67,14 @@ pnpm dev
59
67
 
60
68
  Open `http://localhost:3000` in your browser.
61
69
 
70
+ Start with these files:
71
+
72
+ - `geistdocs.tsx` for the site title, logo, navigation, repository, and AI prompt.
73
+ - `content/docs/index.mdx` for the documentation overview.
74
+ - `content/docs/meta.json` for sidebar order and groups.
75
+
76
+ Only customize `components/geistdocs/*`, `lib/geistdocs/*`, or route adapters when the generated defaults do not fit your site.
77
+
62
78
  ## Edit your first page
63
79
 
64
80
  Docs live in `content/docs`. Edit the overview page:
@@ -116,3 +132,13 @@ pnpm exec geistdocs update
116
132
  ```
117
133
 
118
134
  Review and test dependency changes before committing.
135
+
136
+ ## Verify and deploy
137
+
138
+ Run a production build before publishing:
139
+
140
+ ```bash title="Terminal"
141
+ pnpm build
142
+ ```
143
+
144
+ Then follow [Deploy to Vercel](/docs/deployment), including private package access and environment-variable setup.
@@ -200,7 +200,7 @@ Geistdocs applies a color for each method:
200
200
  | `PUT`, `PATCH` | Amber |
201
201
  | `DEL`, `DELETE` | Red |
202
202
 
203
- Method matching is case-sensitive, so use uppercase labels. `DEL` and `DELETE` render the same red badge, so prefer `DEL` when you want a narrower badge. Any other label, such as `Beta`, keeps the default blue badge. Badge colors adapt to light and dark themes automatically.
203
+ Method matching is case-sensitive, so use uppercase labels. `DEL` and `DELETE` render the same red badge, so prefer `DEL` when you want a narrower badge. `New` renders as a low-contrast blue badge; other labels, such as `Beta`, use the default neutral badge. Badge colors adapt to light and dark themes automatically.
204
204
 
205
205
  ## Add links to the navigation
206
206
 
package/docs/pages/md.md CHANGED
@@ -13,7 +13,7 @@ related:
13
13
 
14
14
  # .md Extension
15
15
 
16
- 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.
16
+ 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.
17
17
 
18
18
  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.
19
19
 
@@ -33,13 +33,13 @@ https://yourdomain.com/docs/getting-started.mdx
33
33
 
34
34
  The `.mdx` version returns:
35
35
 
36
- - The page title as an H1 heading
37
- - The full processed Markdown content
36
+ - Frontmatter with the canonical page URL, docs index, and last-updated date when available
37
+ - The full page content as plain Markdown
38
38
  - No HTML, styling, or navigation
39
39
 
40
40
  For a docs section mounted at `/docs`, the section root remains `/docs.md`. For a source mounted at the app root with `baseUrl: "/"`, Geistdocs uses `/index.md` for the root page. If Next.js has `basePath: "/docs"`, that public root Markdown URL is `/docs/index.md`.
41
41
 
42
- Copy Page, View as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
42
+ Copy Page, View as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. View as Markdown opens the resolved `.md` URL in a new tab from a button, which keeps the URL shareable without adding an anchor to the page. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
43
43
 
44
44
  ## Use cases
45
45
 
@@ -83,11 +83,30 @@ The response includes:
83
83
 
84
84
  - Content-Type: `text/markdown`
85
85
  - `Link: <canonical page URL>; rel="canonical"` for resolved pages
86
- - The page title as a level 1 heading
87
- - Processed Markdown content from Fumadocs
86
+ - Frontmatter with page metadata and discovery links
87
+ - Page content with presentation-only MDX components removed
88
88
 
89
89
  All MDX components are processed and converted to plain Markdown equivalents.
90
90
 
91
+ ### Customize frontmatter
92
+
93
+ 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:
94
+
95
+ ```ts title="lib/geistdocs/source.ts"
96
+ export const geistdocsSource = createSource({
97
+ config,
98
+ docs,
99
+ markdown: {
100
+ frontmatter: (defaults) => ({
101
+ docs_index: "/docs/llms.txt",
102
+ version: "16.3.4",
103
+ }),
104
+ },
105
+ });
106
+ ```
107
+
108
+ The callback returns only additions and overrides; Geistdocs keeps the remaining generated fields from `defaults`.
109
+
91
110
  ## Missing documentation pages
92
111
 
93
112
  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.
@@ -0,0 +1,106 @@
1
+ ---
2
+ title: Migrate from Geistdocs 1.x to 2.0
3
+ description: Upgrade imports, dependencies, and routing without copying Geistdocs internals
4
+ type: guide
5
+ summary: A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.
6
+ url: /docs/migration-2
7
+ source: apps/template/content/docs/migration-2.mdx
8
+ related:
9
+ - /docs/migration
10
+ - /docs/configuration
11
+ - /docs/versioned-docs
12
+ - /docs/proxy
13
+ ---
14
+
15
+ # Migrate from Geistdocs 1.x to 2.0
16
+
17
+ Use this guide only for a site already running Geistdocs 1.x. Geistdocs 2.0 moves shared UI primitives and assets to Geistcn; its package-backed page, source, search, chat, proxy, and agent-readable route APIs remain the preferred integration.
18
+
19
+ Upgrade this Geistdocs site from 1.x to 2.0. Inspect `package.json`, `next.config.ts`, `source.config.ts`, the root layout, `lib/geistdocs`, `proxy.ts`, and all imports from `@vercel/geistdocs/components` or `@vercel/geistdocs/assets`. Upgrade the dependencies, replace removed generic component imports with Geistcn, keep Geistdocs-specific components and route adapters package-backed, and verify every public surface. Do not copy package internals into the app.
20
+
21
+ ## 1. Upgrade dependencies
22
+
23
+ ```bash title="Terminal"
24
+ pnpm add --save-exact @vercel/geistdocs@2 @vercel/geistcn@1.0.3 @vercel/geistcn-assets@2.0.1 next@16.3.3 react@19.2.3 react-dom@19.2.3
25
+ ```
26
+
27
+ Geistdocs requires Node.js 20.9 or later. If the app directly uses Ask AI dependencies, use AI SDK v6 and `@ai-sdk/react` v3. Migrate unrelated AI features separately instead of forking Geistdocs chat code.
28
+
29
+ ## 2. Replace removed imports
30
+
31
+ | Geistdocs 1.x import | Geistdocs 2.0 replacement |
32
+ | --- | --- |
33
+ | `badge`, `button`, `dialog`, `drawer`, `input`, `kbd`, `separator`, `sheet`, `spinner`, `textarea`, `theme-switcher`, or `tooltip` | Import the matching component from `@vercel/geistcn/components/<name>`. |
34
+ | `switch` | Use `@vercel/geistcn/components/toggle`. |
35
+ | `sonner` | Use `Toasts` and `useToasts` from `@vercel/geistcn/components/toasts`. |
36
+ | `theme-aware-image` | Use Geistcn `Image` with `srcLight` and `srcDark`. |
37
+ | `button-group`, `card`, or `input-group` | Choose a Geistcn component or keep an app-owned composition; there is no API-compatible replacement. |
38
+ | `@vercel/geistdocs/assets/icons` or `assets/icons/*` | `@vercel/geistcn-assets/icons` or `icons/*` |
39
+ | `@vercel/geistdocs/assets/logos` or `assets/logos/*` | `@vercel/geistcn-assets/logos` or `logos/*` |
40
+
41
+ Keep documentation-specific imports such as `callout`, `code-block`, `code-block-tabs`, `collapsible`, `command-prompt`, `copy-prompt`, `mermaid`, and `video` on `@vercel/geistdocs/components/*`.
42
+
43
+ Import the package stylesheet once and apply the Geist font classes at the root:
44
+
45
+ ```tsx title="app/[lang]/layout.tsx"
46
+ import "@vercel/geistdocs/styles.css";
47
+ import { geistFontClasses } from "@vercel/geistcn/core";
48
+
49
+ export default function RootLayout({ children }: LayoutProps<"/[lang]">) {
50
+ return (
51
+ <html className={geistFontClasses}>
52
+ <body>{children}</body>
53
+ </html>
54
+ );
55
+ }
56
+ ```
57
+
58
+ ## 3. Use the Next.js and source integrations
59
+
60
+ ```ts title="next.config.ts"
61
+ import { createGeistdocs } from "@vercel/geistdocs/next";
62
+ import type { NextConfig } from "next";
63
+
64
+ const config: NextConfig = {
65
+ modularizeImports: {
66
+ "@vercel/geistcn/components": {
67
+ skipDefaultConversion: true,
68
+ transform: "@vercel/geistcn/components/{{ kebabCase member }}",
69
+ },
70
+ "@vercel/geistcn/core": {
71
+ skipDefaultConversion: true,
72
+ transform: "@vercel/geistcn/core",
73
+ },
74
+ },
75
+ transpilePackages: [
76
+ "@vercel/geistcn",
77
+ "@vercel/geist-test-utils",
78
+ "@vercel/next-themes",
79
+ ],
80
+ cacheComponents: true,
81
+ partialPrefetching: true,
82
+ };
83
+
84
+ export default createGeistdocs()(config);
85
+ ```
86
+
87
+ In `source.config.ts`, import `defineGeistdocsSourceConfig`, `geistdocsFrontmatterSchema`, and `geistdocsMetaSchema` only from `@vercel/geistdocs/source-config`. Keep pages and route handlers as thin adapters around Geistdocs package APIs.
88
+
89
+ ## 4. Preserve routing invariants
90
+
91
+ - If Next.js uses `basePath`, set the same value in Geistdocs config.
92
+ - Keep `content.route`, source `baseUrl`, navigation hrefs, `getPageUrl`, search results, and proxy `markdownRoutes` app-local. Next.js adds the mount prefix once; Geistdocs adds it to public metadata, Markdown, discovery links, and citations.
93
+ - For versioned docs, use `createVersionedSources` and pass server-computed `collectVersionSwitchPaths` to the version selector so missing pages fall back to an existing ancestor.
94
+ - Keep version and router dimensions in static route segments when layouts and sidebar state should persist. Build router-specific, prefix-relative path sets separately from version paths.
95
+ - Keep product-specific navigation titles, badges, related links, and content transforms in the app.
96
+
97
+ ## 5. Verify the upgrade
98
+
99
+ - Run install, typecheck, tests, and a production build.
100
+ - Open representative HTML pages and their `.md` equivalents, including a not-found path.
101
+ - Test search, Ask AI citations, proxy rewrites, and agent-readable routes.
102
+ - Switch versions from pages that do and do not exist in the target version.
103
+ - Confirm links do not trigger broad post-load prefetching and Ask AI is not eagerly loaded.
104
+ - Recheck LCP, CLS, accessibility, and post-render network and CPU activity.
105
+
106
+ For a first migration from Fumadocs or a custom docs site, follow the [full migration guide](/docs/migration).
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: Migration guide
2
+ title: Migrate to Geistdocs
3
3
  description: Migrate a Fumadocs or custom Geist docs site to package-backed Geistdocs
4
4
  type: guide
5
5
  summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
@@ -14,10 +14,13 @@ related:
14
14
  - /docs/agent-readiness
15
15
  ---
16
16
 
17
- # Migration guide
17
+ # Migrate to Geistdocs
18
18
 
19
19
  Migrate an existing Fumadocs or custom Geist documentation site to `@vercel/geistdocs` by moving shared behavior into package APIs and keeping site-specific adapters local. The safest migration keeps content, routing decisions, and product-specific UI in your app while replacing copied runtime code with thin package-backed adapters.
20
20
 
21
+ > Note:
22
+ Follow the concise [1.x → 2.0 guide](/docs/migration-2) instead. This page is for adopting Geistdocs from Fumadocs or a custom documentation site.
23
+
21
24
  Help me migrate this existing docs site to package-backed Geistdocs. Inspect `source.config.ts`, `lib/geistdocs/source.ts`, app route files, `proxy.ts` or `middleware.ts`, `public/llms.txt`, Open Graph routes, Tailwind CSS setup, `package.json` AI SDK dependencies, and environment variables. Then produce a step-by-step migration plan using `@vercel/geistdocs` package APIs without copying package internals.
22
25
 
23
26
  ## Before you migrate
@@ -69,11 +69,17 @@ Headings automatically generate anchor links for navigation and deep linking.
69
69
 
70
70
  Create unordered lists with `-`, `*`, or `+`:
71
71
 
72
- - First item
73
- - Second item
74
- - Nested item
75
- - Another nested item
76
- - Third item
72
+ ```md
73
+ - Install the required packages
74
+ - Configure your project
75
+ - Start the development server
76
+ ```
77
+
78
+ This renders as:
79
+
80
+ - Install the required packages
81
+ - Configure your project
82
+ - Start the development server
77
83
 
78
84
  Create ordered lists with numbers:
79
85
 
@@ -99,6 +105,78 @@ This renders as:
99
105
 
100
106
  > This is automatically set when deploying to Vercel.
101
107
 
108
+ Callouts can also contain a title and lists:
109
+
110
+ > Note:
111
+ - The `App Router` uses [React canary
112
+ releases](https://react.dev/blog/2023/05/03/react-canaries) built-in, which
113
+ include all the stable React 19 changes, as well as newer features being
114
+ validated in frameworks, but you should still declare react and react-dom in
115
+ package.json for tooling and ecosystem compatibility.
116
+ - The `Pages Router` uses the React version from your `package.json`.
117
+
118
+ Callouts support rich inline Markdown, including code, emphasis, and links:
119
+
120
+ ```mdx
121
+ <Callout title="Good to know">
122
+ Global styles can be imported into any layout, page, or component inside the
123
+ `app` directory. However, since Next.js uses React's built-in support for
124
+ stylesheets to integrate with Suspense, this currently does not remove
125
+ stylesheets as you navigate between routes which can lead to conflicts. We
126
+ recommend using global styles for _truly global_ CSS (like Tailwind's base
127
+ styles), [Tailwind CSS](https://tailwindcss.com) for component styling, and
128
+ [CSS Modules](https://nextjs.org/docs/app/getting-started/css#css-modules) for
129
+ custom scoped CSS when needed.
130
+ </Callout>
131
+ ```
132
+
133
+ This renders as:
134
+
135
+ > Note:
136
+ Global styles can be imported into any layout, page, or component inside the
137
+ `app` directory. However, since Next.js uses React's built-in support for
138
+ stylesheets to integrate with Suspense, this currently does not remove
139
+ stylesheets as you navigate between routes which can lead to conflicts. We
140
+ recommend using global styles for _truly global_ CSS (like Tailwind's base
141
+ styles), [Tailwind CSS](https://tailwindcss.com) for component styling, and
142
+ [CSS Modules](https://nextjs.org/docs/app/getting-started/css#css-modules) for
143
+ custom scoped CSS when needed.
144
+
145
+ ### Copy Prompts
146
+
147
+ Short prompts render in full without an expansion control:
148
+
149
+ ```mdx
150
+ <CopyPrompt text="Summarize this documentation page and list the key concepts.">
151
+ Summarize this documentation page and list the key concepts.
152
+ </CopyPrompt>
153
+ ```
154
+
155
+ This renders as:
156
+
157
+ Summarize this documentation page and list the key concepts.
158
+
159
+ Long prompts initially show a preview with a **Show more** control:
160
+
161
+ ```mdx
162
+ <CopyPrompt collapsible text="Write a detailed migration plan for this project.">
163
+ Write a detailed migration plan for this project. Include prerequisites,
164
+ implementation steps, validation, rollback guidance, and common pitfalls.
165
+ </CopyPrompt>
166
+ ```
167
+
168
+ Set the boolean `collapsible` prop when the prompt should initially render as a
169
+ two-line preview. This renders as:
170
+
171
+ Review this Geistdocs project in detail. Explain how the `@vercel/geistdocs`
172
+ package, application layouts, local adapter files, source configuration,
173
+ `content/docs` directory, navigation metadata, MDX components, syntax
174
+ highlighting, search routes, and deployment configuration work together.
175
+ Then identify the safest first files to edit, describe the effect of each
176
+ change, call out common mistakes, and propose a step-by-step plan for
177
+ customizing the documentation site without breaking routing, generated
178
+ Markdown, or accessibility behavior.
179
+
102
180
  ### Links
103
181
 
104
182
  Create links with `[text](url)`:
@@ -106,15 +184,25 @@ Create links with `[text](url)`:
106
184
  - [External link](https://vercel.com)
107
185
  - [Internal link](/docs/getting-started)
108
186
 
109
- Use an absolute `https://` or `http://` URL to mark a link as external. External
110
- links open outside the docs site and display an arrow icon. Use a root-relative
111
- path beginning with `/` for internal links:
187
+ Use an absolute `https://` or `http://` URL for an external destination. Use a
188
+ root-relative path beginning with `/` for an internal link. Both use the same
189
+ visual styling:
112
190
 
113
191
  ```md
114
192
  [External link](https://vercel.com)
115
193
  [Internal link](/docs/getting-started)
116
194
  ```
117
195
 
196
+ Links can also contain inline code:
197
+
198
+ ```md
199
+ Run independent requests in parallel with [`Promise.all`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/all).
200
+ ```
201
+
202
+ This renders as:
203
+
204
+ Run independent requests in parallel with [`Promise.all`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/all).
205
+
118
206
  ### Images
119
207
 
120
208
  Add images with `![alt text](url)`:
@@ -123,6 +211,44 @@ Add images with `![alt text](url)`:
123
211
  ![Description of the image](/path/to/image.png)
124
212
  ```
125
213
 
214
+ Use `<Image>` when an image needs the standard documentation presentation and
215
+ an optional description. It uses Geistcn's image component without a lightbox
216
+ or other interaction:
217
+
218
+ ```mdx
219
+ <Image
220
+ alt="Deployment graph"
221
+ caption="Requests move from the edge to the selected region."
222
+ height={480}
223
+ src="/deployment-graph.png"
224
+ width={800}
225
+ />
226
+ ```
227
+
228
+ This renders as:
229
+
230
+ <Image
231
+ alt="Navigation Inspector showing a loading shell for a page load"
232
+ caption="The Navigation Inspector paused on a page load."
233
+ height={389}
234
+ srcDark="https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/dark/inspector-load.png"
235
+ srcLight="https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/light/inspector-load.png"
236
+ width={472}
237
+ />
238
+
239
+ For theme-aware images, provide both sources:
240
+
241
+ ```mdx
242
+ <Image
243
+ alt="Deployment graph"
244
+ caption="Requests move from the edge to the selected region."
245
+ height={480}
246
+ srcDark="/deployment-graph-dark.png"
247
+ srcLight="/deployment-graph-light.png"
248
+ width={800}
249
+ />
250
+ ```
251
+
126
252
  ## GitHub Flavored Markdown
127
253
 
128
254
  Geistdocs supports GFM extensions including tables, task lists, and autolinks.
@@ -147,6 +273,16 @@ This renders as:
147
273
  | GFM | GitHub extensions | Supported |
148
274
  | MDX | JSX in Markdown | Supported |
149
275
 
276
+ Tables can also include inline code, as commonly used for file references:
277
+
278
+ | File | Description |
279
+ | -------------------- | ------------------------------------------------ |
280
+ | `next.config.js` | Configuration file for Next.js |
281
+ | `package.json` | Project dependencies and scripts |
282
+ | `instrumentation.ts` | OpenTelemetry and instrumentation file |
283
+ | `.env.local` | Local environment variables |
284
+ | `tsconfig.json` | Configuration file for TypeScript |
285
+
150
286
  ### Task Lists
151
287
 
152
288
  Create interactive task lists:
package/docs/sitemap.md CHANGED
@@ -6,8 +6,9 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
6
6
  - [Overview](pages/index.md) | URL: /docs | Type: overview | Summary: Geistdocs is a packaged documentation system for creating Next.js and Fumadocs sites with shared runtime features.
7
7
  - [Getting Started](pages/getting-started.md) | URL: /docs/getting-started | Type: guide | Summary: Create a Geistdocs project, run it locally, and edit your first documentation page.
8
8
  - [Environment Variables](pages/env.md) | URL: /docs/env | Type: reference | Summary: Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
9
- - [Deploy to Vercel](pages/deployment.md) | URL: /docs/deployment | Type: guide | Summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
10
- - [Migration guide](pages/migration.md) | URL: /docs/migration | Type: guide | Summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
9
+ - [Deploy to Vercel](pages/deployment.md) | URL: /docs/deployment | Type: guide | Summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
10
+ - [Migrate to Geistdocs](pages/migration.md) | URL: /docs/migration | Type: guide | Summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
11
+ - [Migrate from Geistdocs 1.x to 2.0](pages/migration-2.md) | URL: /docs/migration-2 | Type: guide | Summary: A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.
11
12
  - [Configuration](pages/configuration.md) | URL: /docs/configuration | Type: reference | Summary: Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
12
13
  - [Syntax](pages/syntax.md) | URL: /docs/syntax | Type: reference | Summary: Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
13
14
  - [Geistdocs Provider](pages/provider.md) | URL: /docs/provider | Type: reference | Summary: The root provider component that wraps your application to handle toast notifications, search, and analytics.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@vercel/geistdocs",
3
3
  "description": "Runtime and CLI for Geistdocs projects.",
4
- "version": "1.25.1-canary.c58830e",
4
+ "version": "1.25.1-canary.d2f4449",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -155,6 +155,10 @@
155
155
  "types": "./dist/components/copy-prompt.d.ts",
156
156
  "default": "./dist/components/copy-prompt.js"
157
157
  },
158
+ "./components/image": {
159
+ "types": "./dist/components/image.d.ts",
160
+ "default": "./dist/components/image.js"
161
+ },
158
162
  "./components/dropdown-menu": {
159
163
  "types": "./dist/components/dropdown-menu.d.ts",
160
164
  "default": "./dist/components/dropdown-menu.js"
@@ -192,10 +196,7 @@
192
196
  "@clack/prompts": "^0.11.0",
193
197
  "@orama/tokenizers": "^3.1.16",
194
198
  "@streamdown/cjk": "^1.0.1",
195
- "@streamdown/code": "^1.0.1",
196
- "@vercel/agent-readability": "^0.6.0",
197
- "@vercel/geistcn": "1.0.3",
198
- "@vercel/geistcn-assets": "2.0.1",
199
+ "@vercel/agent-readability": "^0.7.0",
199
200
  "@vercel/oidc": "^3.4.1",
200
201
  "ai": "^6.0.132",
201
202
  "class-variance-authority": "^0.7.1",
@@ -209,12 +210,14 @@
209
210
  "mermaid": "^11.12.2",
210
211
  "motion": "^12.23.25",
211
212
  "next-themes": "^0.4.6",
213
+ "phase": "^0.5.4",
212
214
  "radix-ui": "1.6.4",
213
215
  "react-player": "^3.4.0",
214
216
  "remark-frontmatter": "^5.0.0",
215
217
  "remark-gfm": "^4.0.1",
216
218
  "remark-mdx": "^3.1.1",
217
219
  "remark-parse": "^11.0.0",
220
+ "remark-stringify": "^11.0.0",
218
221
  "streamdown": "^2.1.0",
219
222
  "ts-morph": "^27.0.2",
220
223
  "tw-animate-css": "^1.4.0",
@@ -224,6 +227,8 @@
224
227
  "zod": "^4.1.13"
225
228
  },
226
229
  "peerDependencies": {
230
+ "@vercel/geistcn": "^1.0.4",
231
+ "@vercel/geistcn-assets": "^2.1.0",
227
232
  "next": "^16.3.3",
228
233
  "react": "^19.2.3",
229
234
  "react-dom": "^19.2.3",
@@ -231,6 +236,8 @@
231
236
  },
232
237
  "devDependencies": {
233
238
  "@biomejs/biome": "^2.3.8",
239
+ "@vercel/geistcn": "1.0.4",
240
+ "@vercel/geistcn-assets": "2.1.0",
234
241
  "@types/glob": "^9.0.0",
235
242
  "@types/mdast": "^4.0.4",
236
243
  "@types/mdx": "^2.0.13",
@@ -3,6 +3,7 @@ import { geistFontClasses } from "@vercel/geistcn/core";
3
3
  import { cn } from "@vercel/geistcn/utils";
4
4
  import "@/lib/geistdocs/site-url-warning";
5
5
  import { Footer } from "@vercel/geistdocs/footer";
6
+ import { GeistdocsThemeScript } from "@vercel/geistdocs/layout";
6
7
  import { Navbar } from "@vercel/geistdocs/navbar";
7
8
  import type { Metadata } from "next";
8
9
  import { GeistdocsProvider } from "@/components/geistdocs/provider";
@@ -30,6 +31,9 @@ const Layout = async ({ children }: LayoutProps<"/[lang]">) => {
30
31
  lang={lang}
31
32
  suppressHydrationWarning
32
33
  >
34
+ <head>
35
+ <GeistdocsThemeScript />
36
+ </head>
33
37
  <body style={{ backgroundColor: "var(--ds-background-200)" }}>
34
38
  <GeistdocsProvider basePath={config.basePath} lang={lang}>
35
39
  <Navbar config={config} />
@@ -45,7 +45,7 @@
45
45
 
46
46
  /* TOC and footer links use gray-1000 */
47
47
  #nd-toc {
48
- @apply text-gray-1000 md:pl-6;
48
+ @apply text-gray-1000;
49
49
  }
50
50
 
51
51
  #nd-toc a {