@vercel/geistdocs 1.25.1-canary.eec231d → 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.
- package/dist/cli/index.js +1 -1
- package/dist/components/code-block-tabs.js +1 -1
- package/dist/components/code-block.d.ts.map +1 -1
- package/dist/components/code-block.js +1 -1
- package/dist/components/copy-prompt.js +1 -1
- package/dist/components/image.d.ts +19 -0
- package/dist/components/image.d.ts.map +1 -0
- package/dist/components/image.js +9 -0
- package/dist/components/steps.d.ts +9 -0
- package/dist/components/steps.d.ts.map +1 -0
- package/dist/components/steps.js +9 -0
- package/dist/internal/chat/activity.d.ts +20 -0
- package/dist/internal/chat/activity.d.ts.map +1 -0
- package/dist/internal/chat/activity.js +43 -0
- package/dist/internal/chat/message-metadata.d.ts.map +1 -1
- package/dist/internal/chat/message-metadata.js +15 -30
- package/dist/internal/chat/message-sources.d.ts +3 -0
- package/dist/internal/chat/message-sources.d.ts.map +1 -0
- package/dist/internal/chat/message-sources.js +23 -0
- package/dist/internal/chat/message.d.ts.map +1 -1
- package/dist/internal/chat/message.js +44 -10
- package/dist/internal/chat/shell.d.ts.map +1 -1
- package/dist/internal/chat/shell.js +7 -2
- package/dist/internal/chat/source-chunks.d.ts +9 -0
- package/dist/internal/chat/source-chunks.d.ts.map +1 -0
- package/dist/internal/chat/source-chunks.js +7 -0
- package/dist/internal/chat/sources.d.ts +1 -1
- package/dist/internal/chat/sources.d.ts.map +1 -1
- package/dist/internal/chat/sources.js +6 -3
- package/dist/internal/link-href.d.ts +13 -0
- package/dist/internal/link-href.d.ts.map +1 -0
- package/dist/internal/link-href.js +51 -0
- package/dist/internal/mdx-to-markdown.d.ts +3 -0
- package/dist/internal/mdx-to-markdown.d.ts.map +1 -0
- package/dist/internal/mdx-to-markdown.js +166 -0
- package/dist/internal/mousedown-navigation-utils.d.ts +5 -0
- package/dist/internal/mousedown-navigation-utils.d.ts.map +1 -0
- package/dist/internal/mousedown-navigation-utils.js +95 -0
- package/dist/internal/mousedown-navigation.d.ts +10 -0
- package/dist/internal/mousedown-navigation.d.ts.map +1 -0
- package/dist/internal/mousedown-navigation.js +42 -0
- package/dist/internal/navbar/navbar-shell.d.ts.map +1 -1
- package/dist/internal/navbar/navbar-shell.js +2 -1
- package/dist/internal/provider-client.d.ts.map +1 -1
- package/dist/internal/provider-client.js +1 -11
- package/dist/internal/react-node-text.d.ts +4 -0
- package/dist/internal/react-node-text.d.ts.map +1 -0
- package/dist/internal/react-node-text.js +11 -0
- package/dist/internal/search.js +1 -1
- package/dist/internal/sidebar-tree.d.ts.map +1 -1
- package/dist/internal/sidebar-tree.js +6 -1
- package/dist/internal/sidebar.d.ts.map +1 -1
- package/dist/internal/sidebar.js +15 -14
- package/dist/internal/table-of-contents-visibility.d.ts +27 -0
- package/dist/internal/table-of-contents-visibility.d.ts.map +1 -0
- package/dist/internal/table-of-contents-visibility.js +15 -0
- package/dist/internal/toc-items.d.ts.map +1 -1
- package/dist/internal/toc-items.js +2 -1
- package/dist/mdx.d.ts +1 -0
- package/dist/mdx.d.ts.map +1 -1
- package/dist/mdx.js +5 -0
- package/dist/page.d.ts +35 -0
- package/dist/page.d.ts.map +1 -0
- package/dist/page.js +26 -0
- package/dist/pages/docs.d.ts +6 -0
- package/dist/pages/docs.d.ts.map +1 -1
- package/dist/pages/docs.js +28 -15
- package/dist/routes/chat.d.ts.map +1 -1
- package/dist/routes/chat.js +30 -13
- package/dist/routes/llms.d.ts +1 -1
- package/dist/routes/llms.d.ts.map +1 -1
- package/dist/routes/llms.js +12 -2
- package/dist/source-config.d.ts +11 -0
- package/dist/source-config.d.ts.map +1 -1
- package/dist/source-config.js +21 -2
- package/dist/source.d.ts +10 -1
- package/dist/source.d.ts.map +1 -1
- package/dist/source.js +75 -34
- package/dist/versions.js +2 -2
- package/docs/agents.md +6 -3
- package/docs/llms.txt +464 -28
- package/docs/manifest.json +30 -3
- package/docs/pages/components/steps.md +129 -0
- package/docs/pages/deployment.md +30 -5
- package/docs/pages/getting-started.md +38 -12
- package/docs/pages/guides/hidden-outline.md +31 -0
- package/docs/pages/guides/nested-navigation.md +1 -1
- package/docs/pages/md.md +24 -5
- package/docs/pages/migration-2.md +106 -0
- package/docs/pages/migration.md +5 -2
- package/docs/pages/syntax.md +42 -0
- package/docs/pages/table-of-contents.md +40 -0
- package/docs/sitemap.md +5 -2
- package/package.json +19 -5
- package/source-config.js +38 -2
- package/template/app/[lang]/docs/custom-page/page.tsx +49 -0
- package/template/content/docs/components/meta.json +4 -0
- package/template/content/docs/components/steps.mdx +125 -0
- package/template/content/docs/deployment.mdx +31 -6
- package/template/content/docs/getting-started.mdx +39 -13
- package/template/content/docs/guides/hidden-outline.mdx +28 -0
- package/template/content/docs/guides/meta.json +1 -1
- package/template/content/docs/guides/nested-navigation.mdx +1 -1
- package/template/content/docs/md.mdx +24 -5
- package/template/content/docs/meta.json +3 -0
- package/template/content/docs/migration-2.mdx +106 -0
- package/template/content/docs/migration.mdx +5 -1
- package/template/content/docs/syntax.mdx +42 -0
- package/template/content/docs/table-of-contents.mdx +40 -0
- package/template/next.config.ts +9 -0
- package/template/package.json +4 -4
- package/theme.css +56 -4
|
@@ -56,6 +56,46 @@ Use `####` when a sub-section needs its own breakdown. Geistdocs indents each le
|
|
|
56
56
|
|
|
57
57
|
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.
|
|
58
58
|
|
|
59
|
+
## Hide the outline on a page
|
|
60
|
+
|
|
61
|
+
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.
|
|
62
|
+
|
|
63
|
+
```yaml
|
|
64
|
+
---
|
|
65
|
+
title: Overview
|
|
66
|
+
tableOfContents: false
|
|
67
|
+
---
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
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`.
|
|
71
|
+
|
|
72
|
+
## Use the outline in custom pages
|
|
73
|
+
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
```tsx title="app/[lang]/docs/overview/page.tsx"
|
|
77
|
+
import {
|
|
78
|
+
GeistdocsPage,
|
|
79
|
+
GeistdocsPageBody,
|
|
80
|
+
GeistdocsPageDescription,
|
|
81
|
+
GeistdocsPageTitle,
|
|
82
|
+
} from "@vercel/geistdocs/page";
|
|
83
|
+
|
|
84
|
+
export default function OverviewPage() {
|
|
85
|
+
return (
|
|
86
|
+
<GeistdocsPage tableOfContents={false}>
|
|
87
|
+
<GeistdocsPageTitle>Overview</GeistdocsPageTitle>
|
|
88
|
+
<GeistdocsPageDescription>
|
|
89
|
+
Start here to find the right guide.
|
|
90
|
+
</GeistdocsPageDescription>
|
|
91
|
+
<GeistdocsPageBody>{/* cards, links, or other content */}</GeistdocsPageBody>
|
|
92
|
+
</GeistdocsPage>
|
|
93
|
+
);
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
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.
|
|
98
|
+
|
|
59
99
|
## Write scannable headings
|
|
60
100
|
|
|
61
101
|
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.
|
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
|
|
10
|
-
- [
|
|
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.
|
|
@@ -19,8 +20,10 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
|
|
|
19
20
|
- [Configure sidebar navigation](pages/guides/nested-navigation.md) | URL: /docs/guides/nested-navigation | Type: guide | Summary: Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.
|
|
20
21
|
- [Edit on GitHub](pages/edit-on-github.md) | URL: /docs/edit-on-github | Type: integration | Summary: A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
|
|
21
22
|
- [Feedback](pages/feedback.md) | URL: /docs/feedback | Type: integration | Summary: An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
|
|
23
|
+
- [Hide the outline](pages/guides/hidden-outline.md) | URL: /docs/guides/hidden-outline | Type: guide | 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.
|
|
22
24
|
- [Internationalization](pages/internationalization.md) | URL: /docs/internationalization | Type: guide | Summary: Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
|
|
23
25
|
- [llms.txt](pages/llms-txt.md) | URL: /docs/llms-txt | Type: conceptual | Summary: A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
|
|
24
26
|
- [Open in Chat](pages/open-in-chat.md) | URL: /docs/open-in-chat | Type: conceptual | Summary: Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
|
|
25
27
|
- [RSS](pages/rss.md) | URL: /docs/rss | Type: conceptual | Summary: An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
|
|
28
|
+
- [Steps](pages/components/steps.md) | URL: /docs/components/steps | Type: reference | 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.
|
|
26
29
|
- [Table of contents](pages/table-of-contents.md) | URL: /docs/table-of-contents | Type: reference | Summary: 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.
|
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.
|
|
4
|
+
"version": "1.25.1-canary.fb7a9dd",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -42,6 +42,10 @@
|
|
|
42
42
|
"types": "./dist/navbar.d.ts",
|
|
43
43
|
"default": "./dist/navbar.js"
|
|
44
44
|
},
|
|
45
|
+
"./page": {
|
|
46
|
+
"types": "./dist/page.d.ts",
|
|
47
|
+
"default": "./dist/page.js"
|
|
48
|
+
},
|
|
45
49
|
"./page-visibility": {
|
|
46
50
|
"types": "./dist/page-visibility.d.ts",
|
|
47
51
|
"default": "./dist/page-visibility.js"
|
|
@@ -155,6 +159,10 @@
|
|
|
155
159
|
"types": "./dist/components/copy-prompt.d.ts",
|
|
156
160
|
"default": "./dist/components/copy-prompt.js"
|
|
157
161
|
},
|
|
162
|
+
"./components/image": {
|
|
163
|
+
"types": "./dist/components/image.d.ts",
|
|
164
|
+
"default": "./dist/components/image.js"
|
|
165
|
+
},
|
|
158
166
|
"./components/dropdown-menu": {
|
|
159
167
|
"types": "./dist/components/dropdown-menu.d.ts",
|
|
160
168
|
"default": "./dist/components/dropdown-menu.js"
|
|
@@ -175,6 +183,10 @@
|
|
|
175
183
|
"types": "./dist/components/scroll-area.d.ts",
|
|
176
184
|
"default": "./dist/components/scroll-area.js"
|
|
177
185
|
},
|
|
186
|
+
"./components/steps": {
|
|
187
|
+
"types": "./dist/components/steps.d.ts",
|
|
188
|
+
"default": "./dist/components/steps.js"
|
|
189
|
+
},
|
|
178
190
|
"./components/video": {
|
|
179
191
|
"types": "./dist/components/video.d.ts",
|
|
180
192
|
"default": "./dist/components/video.js"
|
|
@@ -192,10 +204,7 @@
|
|
|
192
204
|
"@clack/prompts": "^0.11.0",
|
|
193
205
|
"@orama/tokenizers": "^3.1.16",
|
|
194
206
|
"@streamdown/cjk": "^1.0.1",
|
|
195
|
-
"@
|
|
196
|
-
"@vercel/agent-readability": "^0.6.0",
|
|
197
|
-
"@vercel/geistcn": "1.0.3",
|
|
198
|
-
"@vercel/geistcn-assets": "2.0.1",
|
|
207
|
+
"@vercel/agent-readability": "^0.7.0",
|
|
199
208
|
"@vercel/oidc": "^3.4.1",
|
|
200
209
|
"ai": "^6.0.132",
|
|
201
210
|
"class-variance-authority": "^0.7.1",
|
|
@@ -216,6 +225,7 @@
|
|
|
216
225
|
"remark-gfm": "^4.0.1",
|
|
217
226
|
"remark-mdx": "^3.1.1",
|
|
218
227
|
"remark-parse": "^11.0.0",
|
|
228
|
+
"remark-stringify": "^11.0.0",
|
|
219
229
|
"streamdown": "^2.1.0",
|
|
220
230
|
"ts-morph": "^27.0.2",
|
|
221
231
|
"tw-animate-css": "^1.4.0",
|
|
@@ -225,6 +235,8 @@
|
|
|
225
235
|
"zod": "^4.1.13"
|
|
226
236
|
},
|
|
227
237
|
"peerDependencies": {
|
|
238
|
+
"@vercel/geistcn": "^1.0.4",
|
|
239
|
+
"@vercel/geistcn-assets": "^2.1.0",
|
|
228
240
|
"next": "^16.3.3",
|
|
229
241
|
"react": "^19.2.3",
|
|
230
242
|
"react-dom": "^19.2.3",
|
|
@@ -232,6 +244,8 @@
|
|
|
232
244
|
},
|
|
233
245
|
"devDependencies": {
|
|
234
246
|
"@biomejs/biome": "^2.3.8",
|
|
247
|
+
"@vercel/geistcn": "1.0.4",
|
|
248
|
+
"@vercel/geistcn-assets": "2.1.0",
|
|
235
249
|
"@types/glob": "^9.0.0",
|
|
236
250
|
"@types/mdast": "^4.0.4",
|
|
237
251
|
"@types/mdx": "^2.0.13",
|
package/source-config.js
CHANGED
|
@@ -2,7 +2,12 @@ import { execFile } from "node:child_process";
|
|
|
2
2
|
import { readFile } from "node:fs/promises";
|
|
3
3
|
import path from "node:path";
|
|
4
4
|
import { promisify } from "node:util";
|
|
5
|
-
import {
|
|
5
|
+
import {
|
|
6
|
+
remarkHeading,
|
|
7
|
+
remarkMdxMermaid,
|
|
8
|
+
remarkSteps,
|
|
9
|
+
remarkStructure,
|
|
10
|
+
} from "fumadocs-core/mdx-plugins";
|
|
6
11
|
import {
|
|
7
12
|
defineConfig as defineFumadocsConfig,
|
|
8
13
|
frontmatterSchema,
|
|
@@ -224,6 +229,7 @@ export const geistdocsFrontmatterSchema = frontmatterSchema.extend({
|
|
|
224
229
|
.optional(),
|
|
225
230
|
summary: z.string().optional(),
|
|
226
231
|
lastModified: z.coerce.date().optional(),
|
|
232
|
+
tableOfContents: z.boolean().optional(),
|
|
227
233
|
internal: z.boolean().optional(),
|
|
228
234
|
noindex: z.boolean().optional(),
|
|
229
235
|
tags: z.array(z.string()).optional(),
|
|
@@ -236,6 +242,35 @@ export const geistdocsFrontmatterSchema = frontmatterSchema.extend({
|
|
|
236
242
|
|
|
237
243
|
export const geistdocsMetaSchema = metaSchema;
|
|
238
244
|
|
|
245
|
+
const pluginOf = (entry) => (Array.isArray(entry) ? entry[0] : entry);
|
|
246
|
+
|
|
247
|
+
const indexOfPlugin = (list, plugin) =>
|
|
248
|
+
list.findIndex((entry) => pluginOf(entry) === plugin);
|
|
249
|
+
|
|
250
|
+
// Mirrors src/source-config.ts. `remarkSteps` must run before `remarkHeading`,
|
|
251
|
+
// otherwise the `1. ` prefix that marks a step heading leaks into the heading
|
|
252
|
+
// slug and table of contents. Geistdocs and consumer plugins keep their
|
|
253
|
+
// previous slot ahead of `remarkStructure` so search indexing sees their output.
|
|
254
|
+
export const resolveGeistdocsRemarkPlugins = (
|
|
255
|
+
defaults,
|
|
256
|
+
consumerPlugins = []
|
|
257
|
+
) => {
|
|
258
|
+
const list = [...defaults];
|
|
259
|
+
|
|
260
|
+
const headingIndex = indexOfPlugin(list, remarkHeading);
|
|
261
|
+
list.splice(headingIndex === -1 ? 0 : headingIndex, 0, remarkSteps);
|
|
262
|
+
|
|
263
|
+
const structureIndex = indexOfPlugin(list, remarkStructure);
|
|
264
|
+
list.splice(
|
|
265
|
+
structureIndex === -1 ? list.length : structureIndex,
|
|
266
|
+
0,
|
|
267
|
+
remarkMdxMermaid,
|
|
268
|
+
...consumerPlugins
|
|
269
|
+
);
|
|
270
|
+
|
|
271
|
+
return list;
|
|
272
|
+
};
|
|
273
|
+
|
|
239
274
|
export const defineGeistdocsSourceConfig = (config = {}) => {
|
|
240
275
|
const existingRemarkPlugins = Array.isArray(config.mdxOptions?.remarkPlugins)
|
|
241
276
|
? config.mdxOptions.remarkPlugins
|
|
@@ -246,7 +281,8 @@ export const defineGeistdocsSourceConfig = (config = {}) => {
|
|
|
246
281
|
...config,
|
|
247
282
|
mdxOptions: {
|
|
248
283
|
...config.mdxOptions,
|
|
249
|
-
remarkPlugins:
|
|
284
|
+
remarkPlugins: (defaults) =>
|
|
285
|
+
resolveGeistdocsRemarkPlugins(defaults, existingRemarkPlugins),
|
|
250
286
|
rehypeCodeOptions: {
|
|
251
287
|
...config.mdxOptions?.rehypeCodeOptions,
|
|
252
288
|
themes: { light: geistShikiTheme, dark: geistShikiTheme },
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import {
|
|
2
|
+
GeistdocsPage,
|
|
3
|
+
GeistdocsPageBody,
|
|
4
|
+
GeistdocsPageDescription,
|
|
5
|
+
GeistdocsPageTitle,
|
|
6
|
+
} from "@vercel/geistdocs/page";
|
|
7
|
+
import Link from "next/link";
|
|
8
|
+
|
|
9
|
+
export const metadata = {
|
|
10
|
+
title: "Custom page",
|
|
11
|
+
description:
|
|
12
|
+
"A TSX route rendered inside the docs layout with GeistdocsPage and no table of contents.",
|
|
13
|
+
};
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Example of a route built in TSX rather than MDX. It renders inside the docs
|
|
17
|
+
* layout through `GeistdocsPage`, which applies the same table-of-contents
|
|
18
|
+
* behavior as MDX pages.
|
|
19
|
+
*/
|
|
20
|
+
const CustomPage = () => (
|
|
21
|
+
<GeistdocsPage tableOfContents={false}>
|
|
22
|
+
<GeistdocsPageTitle>Custom page</GeistdocsPageTitle>
|
|
23
|
+
<GeistdocsPageDescription>
|
|
24
|
+
This route is a TSX file, not an MDX page. It uses{" "}
|
|
25
|
+
<code>GeistdocsPage</code> with <code>tableOfContents</code> set to{" "}
|
|
26
|
+
<code>false</code>, so no outline renders and the content spans its
|
|
27
|
+
column.
|
|
28
|
+
</GeistdocsPageDescription>
|
|
29
|
+
<GeistdocsPageBody>
|
|
30
|
+
<h2 id="when-to-build-a-page-in-tsx">When to build a page in TSX</h2>
|
|
31
|
+
<p>
|
|
32
|
+
Use a TSX route for landing pages and other layouts that need
|
|
33
|
+
components, data, or structure that MDX does not express well. Content
|
|
34
|
+
pages should stay in MDX so they appear in search, Markdown routes, and
|
|
35
|
+
the sidebar tree.
|
|
36
|
+
</p>
|
|
37
|
+
<h2 id="what-the-shell-provides">What the shell provides</h2>
|
|
38
|
+
<p>
|
|
39
|
+
<code>GeistdocsPage</code> renders the page column, optional breadcrumb
|
|
40
|
+
and footer slots, and the same table of contents that MDX pages use.
|
|
41
|
+
Pass <code>toc</code> items to show an outline. See{" "}
|
|
42
|
+
<Link href="/docs/table-of-contents">Table of contents</Link> for the
|
|
43
|
+
frontmatter equivalent on MDX pages.
|
|
44
|
+
</p>
|
|
45
|
+
</GeistdocsPageBody>
|
|
46
|
+
</GeistdocsPage>
|
|
47
|
+
);
|
|
48
|
+
|
|
49
|
+
export default CustomPage;
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Steps
|
|
3
|
+
description: Render numbered step-by-step instructions from Markdown headings or the Steps and Step components
|
|
4
|
+
type: reference
|
|
5
|
+
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.
|
|
6
|
+
prerequisites:
|
|
7
|
+
- /docs/syntax
|
|
8
|
+
related:
|
|
9
|
+
- /docs/syntax
|
|
10
|
+
- /docs/table-of-contents
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
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.
|
|
14
|
+
|
|
15
|
+
## Write steps as numbered headings
|
|
16
|
+
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
````md
|
|
20
|
+
## Deploy the project
|
|
21
|
+
|
|
22
|
+
### 1. Install the CLI
|
|
23
|
+
|
|
24
|
+
Install the Vercel CLI globally.
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pnpm add -g vercel
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
### 2. Link the project
|
|
31
|
+
|
|
32
|
+
Run `vercel link` in the project directory and pick the team and project.
|
|
33
|
+
|
|
34
|
+
### 3. Deploy
|
|
35
|
+
|
|
36
|
+
Run `vercel deploy` to create a preview deployment.
|
|
37
|
+
|
|
38
|
+
## Next section
|
|
39
|
+
````
|
|
40
|
+
|
|
41
|
+
This renders as:
|
|
42
|
+
|
|
43
|
+
### 1. Install the CLI
|
|
44
|
+
|
|
45
|
+
Install the Vercel CLI globally.
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
pnpm add -g vercel
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### 2. Link the project
|
|
52
|
+
|
|
53
|
+
Run `vercel link` in the project directory and pick the team and project.
|
|
54
|
+
|
|
55
|
+
### 3. Deploy
|
|
56
|
+
|
|
57
|
+
Run `vercel deploy` to create a preview deployment.
|
|
58
|
+
|
|
59
|
+
## How numbering and anchors work
|
|
60
|
+
|
|
61
|
+
Geistdocs removes the `1. ` prefix from the heading text at build time and draws the number with a CSS counter. As a result:
|
|
62
|
+
|
|
63
|
+
- The table of contents shows `Install the CLI`, not `1. Install the CLI`.
|
|
64
|
+
- The heading anchor is `#install-the-cli`, so renumbering steps does not break links.
|
|
65
|
+
- Custom anchors written as `### 1. Install the CLI [#install]` keep working.
|
|
66
|
+
- Markdown routes and `llms.txt` output numbered headings, such as `### 1. Install the CLI`, which read naturally for agents.
|
|
67
|
+
|
|
68
|
+
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.
|
|
69
|
+
|
|
70
|
+
## Rules for grouping steps
|
|
71
|
+
|
|
72
|
+
Geistdocs groups headings into a step list using these rules:
|
|
73
|
+
|
|
74
|
+
| Situation | Result |
|
|
75
|
+
| --- | --- |
|
|
76
|
+
| Consecutive numbered headings at the same depth | One step list |
|
|
77
|
+
| A deeper heading inside a step, such as `#### Options` under `### 2. Configure` | Part of the current step |
|
|
78
|
+
| A heading at the same or shallower depth without a number prefix | Ends the step list |
|
|
79
|
+
| 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` `` |
|
|
80
|
+
|
|
81
|
+
Paragraphs, lists, code blocks, callouts, and images between two step headings belong to the earlier step.
|
|
82
|
+
|
|
83
|
+
## Use the Steps and Step components
|
|
84
|
+
|
|
85
|
+
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`.
|
|
86
|
+
|
|
87
|
+
```mdx
|
|
88
|
+
<Steps>
|
|
89
|
+
<Step>
|
|
90
|
+
### Install the package
|
|
91
|
+
|
|
92
|
+
Run the install command for your package manager.
|
|
93
|
+
</Step>
|
|
94
|
+
<Step>
|
|
95
|
+
### Configure the project
|
|
96
|
+
|
|
97
|
+
Add the configuration file to the project root.
|
|
98
|
+
</Step>
|
|
99
|
+
</Steps>
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
This renders as:
|
|
103
|
+
|
|
104
|
+
<Steps>
|
|
105
|
+
<Step>
|
|
106
|
+
### Install the package
|
|
107
|
+
|
|
108
|
+
Run the install command for your package manager.
|
|
109
|
+
</Step>
|
|
110
|
+
<Step>
|
|
111
|
+
### Configure the project
|
|
112
|
+
|
|
113
|
+
Add the configuration file to the project root.
|
|
114
|
+
</Step>
|
|
115
|
+
</Steps>
|
|
116
|
+
|
|
117
|
+
Do not add a number prefix to headings inside `Step`. The component draws the counter, and a prefix would create a nested step list.
|
|
118
|
+
|
|
119
|
+
### Props
|
|
120
|
+
|
|
121
|
+
`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.
|
|
122
|
+
|
|
123
|
+
## Markdown output
|
|
124
|
+
|
|
125
|
+
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.
|
|
@@ -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
|
|
5
|
+
summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
|
|
6
6
|
prerequisites:
|
|
7
7
|
- /docs/getting-started
|
|
8
8
|
- /docs/env
|
|
@@ -10,10 +10,10 @@ related:
|
|
|
10
10
|
- /docs/configuration
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
-
Deploy a Geistdocs site to Vercel as a Next.js app.
|
|
13
|
+
Deploy a Geistdocs site to Vercel as a Next.js app. Configure private package access, environment variables, and the production URL before shipping.
|
|
14
14
|
|
|
15
|
-
<CopyPrompt text="Help me deploy this Geistdocs project to Vercel.
|
|
16
|
-
Help me deploy this Geistdocs project to Vercel.
|
|
15
|
+
<CopyPrompt text="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.">
|
|
16
|
+
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.
|
|
17
17
|
</CopyPrompt>
|
|
18
18
|
|
|
19
19
|
## Prerequisites
|
|
@@ -24,6 +24,31 @@ Before deploying, you need:
|
|
|
24
24
|
- A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
|
|
25
25
|
- Your Vercel account connected to your GitHub account
|
|
26
26
|
- Environment variables ready (see [Environment Variables](/docs/env))
|
|
27
|
+
- Access to the restricted `@vercel` npm packages
|
|
28
|
+
|
|
29
|
+
## Configure private package access
|
|
30
|
+
|
|
31
|
+
Geistdocs 2.0 depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Package installation fails without npm authentication.
|
|
32
|
+
|
|
33
|
+
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.
|
|
34
|
+
|
|
35
|
+
For GitHub Actions, ask `#help-it` to allow the repository to use the `NPM_TOKEN` organization secret, then pass it to the install step:
|
|
36
|
+
|
|
37
|
+
```yaml title=".github/workflows/check.yml"
|
|
38
|
+
- uses: pnpm/action-setup@v4
|
|
39
|
+
|
|
40
|
+
- uses: actions/setup-node@v4
|
|
41
|
+
with:
|
|
42
|
+
node-version: 20
|
|
43
|
+
cache: pnpm
|
|
44
|
+
registry-url: https://registry.npmjs.org
|
|
45
|
+
|
|
46
|
+
- run: pnpm install
|
|
47
|
+
env:
|
|
48
|
+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Read [How do I use private dependencies with Vercel?](https://vercel.com/kb/guide/using-private-dependencies-with-vercel) for the platform authentication behavior.
|
|
27
52
|
|
|
28
53
|
## Deploy to Vercel
|
|
29
54
|
|
|
@@ -33,9 +58,9 @@ To deploy from the Vercel dashboard:
|
|
|
33
58
|
2. Select your Geistdocs repository
|
|
34
59
|
3. Configure your project settings:
|
|
35
60
|
- **Framework Preset**: Next.js (automatically detected)
|
|
36
|
-
- **Build Command**: `pnpm build`
|
|
61
|
+
- **Build Command**: `pnpm build`
|
|
37
62
|
- **Output Directory**: `.next` (default)
|
|
38
|
-
- **Install Command**: `pnpm install`
|
|
63
|
+
- **Install Command**: `pnpm install`
|
|
39
64
|
4. Add your environment variables (see [Environment Variables](/docs/env))
|
|
40
65
|
5. Click "Deploy"
|
|
41
66
|
|
|
@@ -10,41 +10,49 @@ related:
|
|
|
10
10
|
- /docs/deployment
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
-
Create a Geistdocs site with the package CLI, then
|
|
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.
|
|
16
|
-
Create a Geistdocs project with `pnpm dlx @vercel/geistdocs init --name my-docs`.
|
|
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
|
|
24
|
-
- pnpm
|
|
23
|
+
- Node.js 20.9 or later
|
|
24
|
+
- pnpm
|
|
25
25
|
- Git
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
The CLI always uses pnpm to install the generated project's dependencies.
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
## Authenticate package access
|
|
30
30
|
|
|
31
|
-
|
|
32
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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.
|
|
@@ -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.
|
|
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
|
|