@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
@@ -10,41 +10,49 @@ related:
10
10
  - /docs/deployment
11
11
  ---
12
12
 
13
- 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.
13
+ 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.
14
14
 
15
- <CopyPrompt text="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.">
16
- 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`.
15
+ <CopyPrompt text="Create a new Geistdocs project with pnpm dlx @vercel/geistdocs@latest init --name my-docs. Confirm Node.js 20.9 or later, pnpm, Git, and npm access to the @vercel scope are available first. Then run pnpm dev and help me customize geistdocs.tsx, content/docs/index.mdx, and content/docs/meta.json. Keep the generated route, source, Geistcn, and Next.js integrations package-backed.">
16
+ 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.
17
17
  </CopyPrompt>
18
18
 
19
19
  ## Prerequisites
20
20
 
21
21
  Before you begin, install:
22
22
 
23
- - Node.js 18 or later
24
- - pnpm, npm, or another package manager
23
+ - Node.js 20.9 or later
24
+ - pnpm
25
25
  - Git
26
26
 
27
- ## Create a project
27
+ The CLI always uses pnpm to install the generated project's dependencies.
28
28
 
29
- Run the Geistdocs CLI from an empty parent folder:
29
+ ## Authenticate package access
30
30
 
31
- ```bash title="Terminal"
32
- pnpm dlx @vercel/geistdocs init --name my-docs
31
+ Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Configure your user-level `~/.npmrc` before running the CLI:
32
+
33
+ ```ini title="~/.npmrc"
34
+ @vercel:registry=https://registry.npmjs.org/
35
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
36
+ always-auth=true
33
37
  ```
34
38
 
35
- You can also use npm:
39
+ 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.
40
+
41
+ ## Create a project
42
+
43
+ Run the Geistdocs CLI from an empty parent folder:
36
44
 
37
45
  ```bash title="Terminal"
38
- npx @vercel/geistdocs init --name my-docs
46
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
39
47
  ```
40
48
 
41
49
  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.
42
50
 
43
51
  ## Understand generated dependencies
44
52
 
45
- 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.
53
+ 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.
46
54
 
47
- 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.
55
+ Keep those integrations package-backed. Update Geistdocs instead of copying package internals into the app.
48
56
 
49
57
  ## Start the development server
50
58
 
@@ -57,6 +65,14 @@ pnpm dev
57
65
 
58
66
  Open `http://localhost:3000` in your browser.
59
67
 
68
+ Start with these files:
69
+
70
+ - `geistdocs.tsx` for the site title, logo, navigation, repository, and AI prompt.
71
+ - `content/docs/index.mdx` for the documentation overview.
72
+ - `content/docs/meta.json` for sidebar order and groups.
73
+
74
+ Only customize `components/geistdocs/*`, `lib/geistdocs/*`, or route adapters when the generated defaults do not fit your site.
75
+
60
76
  ## Edit your first page
61
77
 
62
78
  Docs live in `content/docs`. Edit the overview page:
@@ -114,3 +130,13 @@ pnpm exec geistdocs update
114
130
  ```
115
131
 
116
132
  Review and test dependency changes before committing.
133
+
134
+ ## Verify and deploy
135
+
136
+ Run a production build before publishing:
137
+
138
+ ```bash title="Terminal"
139
+ pnpm build
140
+ ```
141
+
142
+ Then follow [Deploy to Vercel](/docs/deployment), including private package access and environment-variable setup.
@@ -0,0 +1,28 @@
1
+ ---
2
+ title: Hide the outline
3
+ description: A page that sets tableOfContents to false so the On this page outline is not rendered and the content spans its column
4
+ type: guide
5
+ 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.
6
+ tableOfContents: false
7
+ related:
8
+ - /docs/table-of-contents
9
+ ---
10
+
11
+ 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.
12
+
13
+ ```yaml
14
+ ---
15
+ title: Hide the outline
16
+ tableOfContents: false
17
+ ---
18
+ ```
19
+
20
+ ## When to hide the outline
21
+
22
+ 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.
23
+
24
+ ## What stays the same
25
+
26
+ 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.
27
+
28
+ See [Table of contents](/docs/table-of-contents) for the complete behavior.
@@ -1,4 +1,4 @@
1
1
  {
2
2
  "title": "Guides",
3
- "pages": ["nested-navigation"]
3
+ "pages": ["nested-navigation", "hidden-outline"]
4
4
  }
@@ -197,7 +197,7 @@ Geistdocs applies a color for each method:
197
197
  | `PUT`, `PATCH` | Amber |
198
198
  | `DEL`, `DELETE` | Red |
199
199
 
200
- 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.
200
+ 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.
201
201
 
202
202
  ## Add links to the navigation
203
203
 
@@ -9,7 +9,7 @@ related:
9
9
  - /docs/proxy
10
10
  ---
11
11
 
12
- 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.
12
+ 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.
13
13
 
14
14
  <CopyPrompt text="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.">
15
15
  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.
@@ -31,8 +31,8 @@ https://yourdomain.com/docs/getting-started.mdx
31
31
 
32
32
  The `.mdx` version returns:
33
33
 
34
- - The page title as an H1 heading
35
- - The full processed Markdown content
34
+ - Frontmatter with the canonical page URL, docs index, and last-updated date when available
35
+ - The full page content as plain Markdown
36
36
  - No HTML, styling, or navigation
37
37
 
38
38
  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`.
@@ -81,11 +81,30 @@ The response includes:
81
81
 
82
82
  - Content-Type: `text/markdown`
83
83
  - `Link: <canonical page URL>; rel="canonical"` for resolved pages
84
- - The page title as a level 1 heading
85
- - Processed Markdown content from Fumadocs
84
+ - Frontmatter with page metadata and discovery links
85
+ - Page content with presentation-only MDX components removed
86
86
 
87
87
  All MDX components are processed and converted to plain Markdown equivalents.
88
88
 
89
+ ### Customize frontmatter
90
+
91
+ 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:
92
+
93
+ ```ts title="lib/geistdocs/source.ts"
94
+ export const geistdocsSource = createSource({
95
+ config,
96
+ docs,
97
+ markdown: {
98
+ frontmatter: (defaults) => ({
99
+ docs_index: "/docs/llms.txt",
100
+ version: "16.3.4",
101
+ }),
102
+ },
103
+ });
104
+ ```
105
+
106
+ The callback returns only additions and overrides; Geistdocs keeps the remaining generated fields from `defaults`.
107
+
89
108
  ## Missing documentation pages
90
109
 
91
110
  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.
@@ -9,12 +9,15 @@
9
9
  "env",
10
10
  "deployment",
11
11
  "migration",
12
+ "migration-2",
12
13
  "configuration",
13
14
  "---Internals---",
14
15
  "syntax",
15
16
  "provider",
16
17
  "versioned-docs",
17
18
  "proxy",
19
+ "---Components---",
20
+ "components",
18
21
  "---Features---",
19
22
  "...",
20
23
  "---AI---",
@@ -0,0 +1,106 @@
1
+ ---
2
+ title: Migrate from Geistdocs 1.x to 2.0
3
+ navTitle: Migrate 1.x → 2.0
4
+ badge: New
5
+ description: Upgrade imports, dependencies, and routing without copying Geistdocs internals
6
+ type: guide
7
+ summary: A concise, agent-friendly checklist for upgrading an existing Geistdocs 1.x site to 2.0.
8
+ related:
9
+ - /docs/migration
10
+ - /docs/configuration
11
+ - /docs/versioned-docs
12
+ - /docs/proxy
13
+ ---
14
+
15
+ 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.
16
+
17
+ <CopyPrompt text="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 @vercel/geistcn/components/*, replace icon and logo imports with @vercel/geistcn-assets, keep Geistdocs-specific components and all route adapters package-backed, enable cacheComponents and partialPrefetching, apply geistFontClasses once, and preserve app-local paths when basePath is configured. If the site has versions, use createVersionedSources and pass collectVersionSwitchPaths to the version selector. Run install, typecheck, and build, then verify HTML, Markdown, search, Ask AI, and version fallbacks. Do not copy package internals into the app.">
18
+ 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.
19
+ </CopyPrompt>
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,6 +14,10 @@ related:
14
14
 
15
15
  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.
16
16
 
17
+ <Callout title="Already use Geistdocs 1.x?">
18
+ 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.
19
+ </Callout>
20
+
17
21
  <CopyPrompt text="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.">
18
22
  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.
19
23
  </CopyPrompt>
@@ -85,6 +85,10 @@ Create ordered lists with numbers:
85
85
  2. Second step
86
86
  3. Third step
87
87
 
88
+ ### Steps
89
+
90
+ 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.
91
+
88
92
  ### Blockquotes
89
93
 
90
94
  Use `>` to create blockquotes:
@@ -114,6 +118,34 @@ Callouts can also contain a title and lists:
114
118
  - The `Pages Router` uses the React version from your `package.json`.
115
119
  </Callout>
116
120
 
121
+ Callouts support rich inline Markdown, including code, emphasis, and links:
122
+
123
+ ```mdx
124
+ <Callout title="Good to know">
125
+ Global styles can be imported into any layout, page, or component inside the
126
+ `app` directory. However, since Next.js uses React's built-in support for
127
+ stylesheets to integrate with Suspense, this currently does not remove
128
+ stylesheets as you navigate between routes which can lead to conflicts. We
129
+ recommend using global styles for _truly global_ CSS (like Tailwind's base
130
+ styles), [Tailwind CSS](https://tailwindcss.com) for component styling, and
131
+ [CSS Modules](https://nextjs.org/docs/app/getting-started/css#css-modules) for
132
+ custom scoped CSS when needed.
133
+ </Callout>
134
+ ```
135
+
136
+ This renders as:
137
+
138
+ <Callout title="Good to know">
139
+ Global styles can be imported into any layout, page, or component inside the
140
+ `app` directory. However, since Next.js uses React's built-in support for
141
+ stylesheets to integrate with Suspense, this currently does not remove
142
+ stylesheets as you navigate between routes which can lead to conflicts. We
143
+ recommend using global styles for _truly global_ CSS (like Tailwind's base
144
+ styles), [Tailwind CSS](https://tailwindcss.com) for component styling, and
145
+ [CSS Modules](https://nextjs.org/docs/app/getting-started/css#css-modules) for
146
+ custom scoped CSS when needed.
147
+ </Callout>
148
+
117
149
  ### Copy Prompts
118
150
 
119
151
  Short prompts render in full without an expansion control:
@@ -160,17 +192,16 @@ Create links with `[text](url)`:
160
192
  - [External link](https://vercel.com)
161
193
  - [Internal link](/docs/getting-started)
162
194
 
163
- Use an absolute `https://` or `http://` URL to mark a link as external. External
164
- links open outside the docs site and display an arrow icon. Use a root-relative
165
- path beginning with `/` for internal links:
195
+ Use an absolute `https://` or `http://` URL for an external destination. Use a
196
+ root-relative path beginning with `/` for an internal link. Both use the same
197
+ visual styling:
166
198
 
167
199
  ```md
168
200
  [External link](https://vercel.com)
169
201
  [Internal link](/docs/getting-started)
170
202
  ```
171
203
 
172
- External links can also contain inline code. The underline applies to the text,
173
- but not the external-link icon:
204
+ Links can also contain inline code:
174
205
 
175
206
  ```md
176
207
  Run independent requests in parallel with [`Promise.all`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/all).
@@ -188,6 +219,44 @@ Add images with `![alt text](url)`:
188
219
  ![Description of the image](/path/to/image.png)
189
220
  ```
190
221
 
222
+ Use `<Image>` when an image needs the standard documentation presentation and
223
+ an optional description. It uses Geistcn's image component without a lightbox
224
+ or other interaction:
225
+
226
+ ```mdx
227
+ <Image
228
+ alt="Deployment graph"
229
+ caption="Requests move from the edge to the selected region."
230
+ height={480}
231
+ src="/deployment-graph.png"
232
+ width={800}
233
+ />
234
+ ```
235
+
236
+ This renders as:
237
+
238
+ <Image
239
+ alt="Navigation Inspector showing a loading shell for a page load"
240
+ caption="The Navigation Inspector paused on a page load."
241
+ height={389}
242
+ srcDark="https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/dark/inspector-load.png"
243
+ srcLight="https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/light/inspector-load.png"
244
+ width={472}
245
+ />
246
+
247
+ For theme-aware images, provide both sources:
248
+
249
+ ```mdx
250
+ <Image
251
+ alt="Deployment graph"
252
+ caption="Requests move from the edge to the selected region."
253
+ height={480}
254
+ srcDark="/deployment-graph-dark.png"
255
+ srcLight="/deployment-graph-light.png"
256
+ width={800}
257
+ />
258
+ ```
259
+
191
260
  ## GitHub Flavored Markdown
192
261
 
193
262
  Geistdocs supports GFM extensions including tables, task lists, and autolinks.
@@ -52,6 +52,46 @@ Use `####` when a sub-section needs its own breakdown. Geistdocs indents each le
52
52
 
53
53
  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.
54
54
 
55
+ ## Hide the outline on a page
56
+
57
+ 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.
58
+
59
+ ```yaml
60
+ ---
61
+ title: Overview
62
+ tableOfContents: false
63
+ ---
64
+ ```
65
+
66
+ 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`.
67
+
68
+ ## Use the outline in custom pages
69
+
70
+ 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.
71
+
72
+ ```tsx title="app/[lang]/docs/overview/page.tsx"
73
+ import {
74
+ GeistdocsPage,
75
+ GeistdocsPageBody,
76
+ GeistdocsPageDescription,
77
+ GeistdocsPageTitle,
78
+ } from "@vercel/geistdocs/page";
79
+
80
+ export default function OverviewPage() {
81
+ return (
82
+ <GeistdocsPage tableOfContents={false}>
83
+ <GeistdocsPageTitle>Overview</GeistdocsPageTitle>
84
+ <GeistdocsPageDescription>
85
+ Start here to find the right guide.
86
+ </GeistdocsPageDescription>
87
+ <GeistdocsPageBody>{/* cards, links, or other content */}</GeistdocsPageBody>
88
+ </GeistdocsPage>
89
+ );
90
+ }
91
+ ```
92
+
93
+ 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.
94
+
55
95
  ## Write scannable headings
56
96
 
57
97
  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.
@@ -23,6 +23,15 @@ const environment = process.env.VERCEL_ENV ?? process.env.NODE_ENV;
23
23
  const envFavicon = ENV_FAVICONS[environment as keyof typeof ENV_FAVICONS];
24
24
 
25
25
  const config: NextConfig = {
26
+ images: {
27
+ remotePatterns: [
28
+ {
29
+ hostname: "h8dxkfmaphn8o0p3.public.blob.vercel-storage.com",
30
+ pathname: "/docs/**",
31
+ protocol: "https",
32
+ },
33
+ ],
34
+ },
26
35
  modularizeImports: {
27
36
  "@vercel/geistcn/components": {
28
37
  skipDefaultConversion: true,
@@ -15,11 +15,11 @@
15
15
  "@orama/tokenizers": "^3.1.16",
16
16
  "@streamdown/cjk": "^1.0.1",
17
17
  "@streamdown/code": "^1.0.1",
18
- "@vercel/agent-readability": "^0.6.0",
18
+ "@vercel/agent-readability": "^0.7.0",
19
19
  "@vercel/analytics": "^1.6.1",
20
- "@vercel/geistcn": "1.0.3",
21
- "@vercel/geistcn-assets": "2.0.1",
22
- "@vercel/geistdocs": "1.25.1-canary.f56ac48",
20
+ "@vercel/geistcn": "1.0.4",
21
+ "@vercel/geistcn-assets": "2.1.0",
22
+ "@vercel/geistdocs": "1.25.1-canary.fb7a9dd",
23
23
  "@vercel/speed-insights": "^1.3.1",
24
24
  "ai": "^6.0.132",
25
25
  "class-variance-authority": "^0.7.1",
package/theme.css CHANGED
@@ -60,6 +60,56 @@ button:not(:disabled, [aria-disabled="true"]) {
60
60
  padding-left: 0.5rem;
61
61
  }
62
62
 
63
+ /* Numbered steps. Overrides the fumadocs rail-and-disc layout with a bordered
64
+ Geist counter aligned to each step heading. Emitted by remarkSteps for
65
+ `### 1. Title` headings and by the Steps/Step components. */
66
+ .prose .fd-steps {
67
+ --geistdocs-step-size: 1.75rem;
68
+ padding-left: 0;
69
+ margin-top: 1.5rem;
70
+ margin-left: 0;
71
+ counter-reset: step;
72
+ border-left: 0;
73
+ }
74
+
75
+ .prose .fd-step {
76
+ position: relative;
77
+ padding-bottom: 2rem;
78
+ padding-left: calc(var(--geistdocs-step-size) + 0.75rem);
79
+ }
80
+
81
+ .prose .fd-step:last-child {
82
+ padding-bottom: 0;
83
+ }
84
+
85
+ .prose .fd-step::before {
86
+ position: absolute;
87
+ top: -1px;
88
+ left: 0;
89
+ display: flex;
90
+ align-items: center;
91
+ justify-content: center;
92
+ width: var(--geistdocs-step-size);
93
+ height: var(--geistdocs-step-size);
94
+ font-size: 0.8125rem;
95
+ font-weight: 500;
96
+ line-height: 1;
97
+ color: var(--ds-gray-1000);
98
+ content: counter(step);
99
+ counter-increment: step;
100
+ background-color: var(--ds-background-100);
101
+ border: 1px solid var(--ds-gray-400);
102
+ border-radius: 9999px;
103
+ }
104
+
105
+ .prose .fd-step > :first-child {
106
+ margin-top: 0;
107
+ }
108
+
109
+ .prose .fd-step > :last-child {
110
+ margin-bottom: 0;
111
+ }
112
+
63
113
  #nd-page h1:not(:where(.prose *)) {
64
114
  @apply text-heading-40 tracking-tighter;
65
115
  }
@@ -69,6 +119,12 @@ button:not(:disabled, [aria-disabled="true"]) {
69
119
  max-width: 780px;
70
120
  transform: translateX(-20px);
71
121
  }
122
+
123
+ /* Pages without an outline (`tableOfContents: false`) extend the content
124
+ across the column the outline would have used. */
125
+ #nd-page[data-full="true"] {
126
+ max-width: calc(780px + var(--geistdocs-toc-column, 268px));
127
+ }
72
128
  }
73
129
 
74
130
  @layer utilities {
@@ -227,10 +283,6 @@ button:not(:disabled, [aria-disabled="true"]) {
227
283
  }
228
284
  }
229
285
 
230
- [data-geistdocs-command-modal] {
231
- box-shadow: var(--ds-shadow-modal);
232
- }
233
-
234
286
  [data-geistdocs-command-modal] .text-fd-muted-foreground {
235
287
  color: var(--ds-gray-900);
236
288
  }