@vercel/geistdocs 1.3.1 → 1.4.1
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/config.d.ts +6 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/routes/agents.d.ts.map +1 -1
- package/dist/routes/agents.js +14 -29
- package/dist/routes/discovery.d.ts +14 -0
- package/dist/routes/discovery.d.ts.map +1 -0
- package/dist/routes/discovery.js +74 -0
- package/dist/routes/mcp.d.ts +26 -0
- package/dist/routes/mcp.d.ts.map +1 -0
- package/dist/routes/mcp.js +31 -0
- package/dist/source.d.ts +1 -1
- package/dist/source.d.ts.map +1 -1
- package/dist/source.js +4 -1
- package/docs/agents.md +44 -0
- package/docs/llms.txt +2965 -0
- package/docs/manifest.json +194 -0
- package/docs/pages/agent-readiness.md +141 -0
- package/docs/pages/ask-ai.md +143 -0
- package/docs/pages/configuration.md +278 -0
- package/docs/pages/deployment.md +53 -0
- package/docs/pages/edit-on-github.md +53 -0
- package/docs/pages/env.md +62 -0
- package/docs/pages/feedback.md +91 -0
- package/docs/pages/getting-started.md +116 -0
- package/docs/pages/index.md +99 -0
- package/docs/pages/internationalization.md +124 -0
- package/docs/pages/llms-txt.md +88 -0
- package/docs/pages/md.md +84 -0
- package/docs/pages/migration.md +376 -0
- package/docs/pages/open-in-chat.md +82 -0
- package/docs/pages/provider.md +76 -0
- package/docs/pages/proxy.md +180 -0
- package/docs/pages/rss.md +110 -0
- package/docs/pages/syntax.md +413 -0
- package/docs/pages/theme-aware-image.md +59 -0
- package/docs/pages/versioned-docs.md +230 -0
- package/docs/sitemap.md +25 -0
- package/package.json +12 -2
- package/styles.css +174 -0
- package/template/AGENTS.md +10 -3
- package/template/app/[lang]/.well-known/mcp.json/route.ts +8 -0
- package/template/content/docs/agent-readiness.mdx +44 -8
- package/template/content/docs/configuration.mdx +1 -0
- package/template/content/docs/index.mdx +1 -1
- package/template/content/docs/llms-txt.mdx +1 -1
- package/template/content/docs/migration.mdx +12 -2
- package/template/package.json +1 -1
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Configuration
|
|
3
|
+
description: Configure a Geistdocs site through local adapter files and package APIs
|
|
4
|
+
type: reference
|
|
5
|
+
summary: Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
|
|
6
|
+
url: /docs/configuration
|
|
7
|
+
source: apps/template/content/docs/configuration.mdx
|
|
8
|
+
prerequisites:
|
|
9
|
+
- /docs/getting-started
|
|
10
|
+
related:
|
|
11
|
+
- /docs/migration
|
|
12
|
+
- /docs/provider
|
|
13
|
+
- /docs/env
|
|
14
|
+
- /docs/versioned-docs
|
|
15
|
+
- /docs/proxy
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
# Configuration
|
|
19
|
+
|
|
20
|
+
Configure Geistdocs through user-owned files in the generated project. Runtime features come from `@vercel/geistdocs`, while your local files control content, branding, routing adapters, and opt-in customization.
|
|
21
|
+
|
|
22
|
+
Review this Geistdocs project configuration. Explain what each export in `geistdocs.tsx` does, identify which features are enabled, and suggest safe customizations that do not require editing package internals.
|
|
23
|
+
|
|
24
|
+
## Configuration files
|
|
25
|
+
|
|
26
|
+
| File | Purpose |
|
|
27
|
+
| --- | --- |
|
|
28
|
+
| `geistdocs.tsx` | Site-level settings, including logo, nav, GitHub repo, AI prompt, agent-readiness metadata, translations, and feature flags. |
|
|
29
|
+
| `source.config.ts` | Configures Fumadocs collections with the package-provided schema, Markdown plugins, and syntax theme. |
|
|
30
|
+
| `lib/geistdocs/config.tsx` | Converts `geistdocs.tsx` exports into the package config using `defineConfig`. |
|
|
31
|
+
| `source.config.ts` | Configures Fumadocs collections with package-safe schemas and Markdown processing. |
|
|
32
|
+
| `lib/geistdocs/source.ts` | Connects Fumadocs content collections to the package source adapter. |
|
|
33
|
+
| `components/geistdocs/mdx-components.tsx` | Adds or overrides MDX components. |
|
|
34
|
+
| `components/geistdocs/docs-layout.tsx` | Customizes the package-backed docs layout, including optional sidebar content. |
|
|
35
|
+
| `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
|
|
36
|
+
| `app/[lang]/agents.md/route.ts` | Configures the agent-readiness entry point. |
|
|
37
|
+
| `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery. |
|
|
38
|
+
| `app/[lang]/llms.txt/route.ts` | Configures the all-docs Markdown endpoint. |
|
|
39
|
+
| `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses. |
|
|
40
|
+
| `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
|
|
41
|
+
| `content/docs/meta.json` | Controls sidebar order and section labels. |
|
|
42
|
+
|
|
43
|
+
## `geistdocs.tsx`
|
|
44
|
+
|
|
45
|
+
The root `geistdocs.tsx` file is the primary configuration surface:
|
|
46
|
+
|
|
47
|
+
```tsx title="geistdocs.tsx"
|
|
48
|
+
export const Logo = () => <span>My Docs</span>;
|
|
49
|
+
|
|
50
|
+
export const github = {
|
|
51
|
+
owner: "my-org",
|
|
52
|
+
repo: "my-repo",
|
|
53
|
+
branch: "main",
|
|
54
|
+
editPath: "content/docs/{path}",
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
export const nav = [
|
|
58
|
+
{ label: "Docs", href: "/docs" },
|
|
59
|
+
{ label: "GitHub", href: "https://github.com/my-org/my-repo" },
|
|
60
|
+
];
|
|
61
|
+
|
|
62
|
+
export const title = "My Documentation";
|
|
63
|
+
|
|
64
|
+
export const prompt =
|
|
65
|
+
"You are a helpful assistant that answers questions about My Documentation.";
|
|
66
|
+
|
|
67
|
+
export const suggestions = [
|
|
68
|
+
"How do I get started?",
|
|
69
|
+
"How do I deploy?",
|
|
70
|
+
];
|
|
71
|
+
|
|
72
|
+
export const agent = {
|
|
73
|
+
product: {
|
|
74
|
+
name: "My Product",
|
|
75
|
+
description: "My Product helps teams build and deploy applications.",
|
|
76
|
+
},
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
export const translations = {
|
|
80
|
+
en: { displayName: "English" },
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
export const basePath: string | undefined = undefined;
|
|
84
|
+
export const siteId: string | undefined = undefined;
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## `defineConfig`
|
|
88
|
+
|
|
89
|
+
`lib/geistdocs/config.tsx` converts your root exports into a package config. Most projects only need the generated defaults:
|
|
90
|
+
|
|
91
|
+
```tsx title="lib/geistdocs/config.tsx"
|
|
92
|
+
import { defineConfig } from "@vercel/geistdocs/config";
|
|
93
|
+
import {
|
|
94
|
+
agent,
|
|
95
|
+
basePath,
|
|
96
|
+
github,
|
|
97
|
+
Logo,
|
|
98
|
+
nav,
|
|
99
|
+
prompt,
|
|
100
|
+
siteId,
|
|
101
|
+
suggestions,
|
|
102
|
+
title,
|
|
103
|
+
translations,
|
|
104
|
+
} from "@/geistdocs";
|
|
105
|
+
|
|
106
|
+
export const config = defineConfig({
|
|
107
|
+
title,
|
|
108
|
+
agent,
|
|
109
|
+
defaultLanguage: "en",
|
|
110
|
+
logo: <Logo />,
|
|
111
|
+
github,
|
|
112
|
+
nav,
|
|
113
|
+
basePath,
|
|
114
|
+
siteId,
|
|
115
|
+
translations,
|
|
116
|
+
ai: {
|
|
117
|
+
prompt,
|
|
118
|
+
suggestions,
|
|
119
|
+
},
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Advanced sites can add `content` and `versions` metadata so local adapters and custom UI share one configuration object:
|
|
124
|
+
|
|
125
|
+
```tsx title="lib/geistdocs/config.tsx"
|
|
126
|
+
export const config = defineConfig({
|
|
127
|
+
// ...
|
|
128
|
+
content: [
|
|
129
|
+
{ id: "docs", label: "Docs", dir: "content/docs", route: "/docs" },
|
|
130
|
+
{
|
|
131
|
+
id: "cookbook",
|
|
132
|
+
label: "Cookbook",
|
|
133
|
+
dir: "content/cookbook",
|
|
134
|
+
route: "/cookbook",
|
|
135
|
+
},
|
|
136
|
+
],
|
|
137
|
+
versions: {
|
|
138
|
+
current: "v6",
|
|
139
|
+
items: [
|
|
140
|
+
{ id: "v6", label: "v6 latest" },
|
|
141
|
+
{ id: "v5", label: "v5", href: "https://v5.example.com/:path*" },
|
|
142
|
+
],
|
|
143
|
+
},
|
|
144
|
+
});
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
|
|
148
|
+
|
|
149
|
+
## `source.config.ts`
|
|
150
|
+
|
|
151
|
+
Use the source-config-safe package export in `source.config.ts`. This file is evaluated by `fumadocs-mdx` during install and build, so it should avoid imports from runtime component entry points such as `@vercel/geistdocs/mdx`.
|
|
152
|
+
|
|
153
|
+
```ts title="source.config.ts"
|
|
154
|
+
import {
|
|
155
|
+
defineGeistdocsSourceConfig,
|
|
156
|
+
geistdocsFrontmatterSchema,
|
|
157
|
+
geistdocsMetaSchema,
|
|
158
|
+
} from "@vercel/geistdocs/source-config";
|
|
159
|
+
import { defineDocs } from "fumadocs-mdx/config";
|
|
160
|
+
|
|
161
|
+
export const docs = defineDocs({
|
|
162
|
+
dir: "content/docs",
|
|
163
|
+
docs: {
|
|
164
|
+
schema: geistdocsFrontmatterSchema,
|
|
165
|
+
postprocess: {
|
|
166
|
+
includeProcessedMarkdown: true,
|
|
167
|
+
},
|
|
168
|
+
},
|
|
169
|
+
meta: {
|
|
170
|
+
schema: geistdocsMetaSchema,
|
|
171
|
+
},
|
|
172
|
+
});
|
|
173
|
+
|
|
174
|
+
export default defineGeistdocsSourceConfig();
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/"` in `createSource`. Root-mounted docs need explicit `markdownRoutes`; Geistdocs does not infer a broad `/*path` mapping because it can capture homepages and non-docs app routes.
|
|
178
|
+
|
|
179
|
+
## Page actions
|
|
180
|
+
|
|
181
|
+
Page actions appear below the table of contents. They are enabled by default and can be disabled through `defineConfig` in `lib/geistdocs/config.tsx`:
|
|
182
|
+
|
|
183
|
+
```tsx title="lib/geistdocs/config.tsx"
|
|
184
|
+
export const config = defineConfig({
|
|
185
|
+
// ...
|
|
186
|
+
pageActions: {
|
|
187
|
+
editSource: false,
|
|
188
|
+
scrollTop: true,
|
|
189
|
+
copyPage: true,
|
|
190
|
+
askAI: true,
|
|
191
|
+
openInChat: false,
|
|
192
|
+
},
|
|
193
|
+
feedback: {
|
|
194
|
+
enabled: false,
|
|
195
|
+
},
|
|
196
|
+
});
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`github.editPath` controls the file path used by the "Edit this page on GitHub" action. Use `{path}` where the page path should be inserted. For monorepos, include the app directory, such as `apps/docs/content/docs/{path}`.
|
|
200
|
+
|
|
201
|
+
## Page visibility
|
|
202
|
+
|
|
203
|
+
Use frontmatter to control whether a page appears in package-owned machine-readable surfaces:
|
|
204
|
+
|
|
205
|
+
```mdx title="content/docs/internal-note.mdx"
|
|
206
|
+
---
|
|
207
|
+
title: Internal note
|
|
208
|
+
description: Hidden from public indexes
|
|
209
|
+
internal: true
|
|
210
|
+
---
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
`internal: true` excludes a page from `llms.txt`, `sitemap.md`, search, and chat. `noindex: true` adds `robots: noindex` metadata and excludes the page from `sitemap.md`. Use `excludeFrom` for per-surface control:
|
|
214
|
+
|
|
215
|
+
```mdx
|
|
216
|
+
---
|
|
217
|
+
title: Draft guide
|
|
218
|
+
excludeFrom:
|
|
219
|
+
- chat
|
|
220
|
+
- search
|
|
221
|
+
---
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Optional `tags`, `keywords`, and `canonical` frontmatter are also recognized by the package runtime.
|
|
225
|
+
|
|
226
|
+
## User-owned adapters
|
|
227
|
+
|
|
228
|
+
Adapter files are safe to edit. Package updates do not overwrite them.
|
|
229
|
+
|
|
230
|
+
For example, add a custom MDX component:
|
|
231
|
+
|
|
232
|
+
```tsx title="components/geistdocs/mdx-components.tsx"
|
|
233
|
+
import { createMdxComponents } from "@vercel/geistdocs/mdx";
|
|
234
|
+
import type { MDXComponents } from "mdx/types";
|
|
235
|
+
|
|
236
|
+
const ProductCard = ({ name }: { name: string }) => <div>{name}</div>;
|
|
237
|
+
|
|
238
|
+
export const getMDXComponents = (components?: MDXComponents): MDXComponents =>
|
|
239
|
+
createMdxComponents({
|
|
240
|
+
ProductCard,
|
|
241
|
+
...components,
|
|
242
|
+
});
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Then use it in MDX:
|
|
246
|
+
|
|
247
|
+
```mdx
|
|
248
|
+
<ProductCard name="My product" />
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
## Docs page adapter
|
|
252
|
+
|
|
253
|
+
`createDocsPage` accepts hooks for route-specific behavior:
|
|
254
|
+
|
|
255
|
+
```tsx title="app/[lang]/docs/[[...slug]]/page.tsx"
|
|
256
|
+
const docsPage = createDocsPage({
|
|
257
|
+
config,
|
|
258
|
+
source: geistdocsSource,
|
|
259
|
+
getPageUrl: ({ page }) => page.url,
|
|
260
|
+
openGraph: {
|
|
261
|
+
images: true,
|
|
262
|
+
},
|
|
263
|
+
metadata: ({ metadata }) => metadata,
|
|
264
|
+
mdx: ({ link }) => getMDXComponents({ a: link }),
|
|
265
|
+
});
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Use `getPageUrl` when the public route differs from the source URL, such as `/v5/docs`. Set `openGraph.images` to `true` only when your site includes the Geistdocs OG route. Use `metadata` to set canonical URLs, `robots`, or custom Open Graph fields for a specific route.
|
|
269
|
+
|
|
270
|
+
## Package-owned runtime
|
|
271
|
+
|
|
272
|
+
Do not edit files inside `node_modules/@vercel/geistdocs`. Update the package instead:
|
|
273
|
+
|
|
274
|
+
```bash title="Terminal"
|
|
275
|
+
pnpm exec geistdocs update
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
If a release adds an optional prop or config field, opt into it by editing the relevant local adapter file. Existing adapters should keep compiling unless a release includes a breaking API change.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Deploy to Vercel
|
|
3
|
+
description: Learn how to deploy your Geistdocs site to Vercel
|
|
4
|
+
type: guide
|
|
5
|
+
summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
|
|
6
|
+
url: /docs/deployment
|
|
7
|
+
source: apps/template/content/docs/deployment.mdx
|
|
8
|
+
prerequisites:
|
|
9
|
+
- /docs/getting-started
|
|
10
|
+
- /docs/env
|
|
11
|
+
related:
|
|
12
|
+
- /docs/configuration
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Deploy to Vercel
|
|
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.
|
|
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.
|
|
20
|
+
|
|
21
|
+
## Prerequisites
|
|
22
|
+
|
|
23
|
+
Before deploying, you need:
|
|
24
|
+
|
|
25
|
+
- A [GitHub account](https://github.com) with your Geistdocs repository
|
|
26
|
+
- A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
|
|
27
|
+
- Your Vercel account connected to your GitHub account
|
|
28
|
+
- Environment variables ready (see [Environment Variables](/docs/env))
|
|
29
|
+
|
|
30
|
+
## Deploy to Vercel
|
|
31
|
+
|
|
32
|
+
To deploy from the Vercel dashboard:
|
|
33
|
+
|
|
34
|
+
1. Go to [vercel.com/new](https://vercel.com/new)
|
|
35
|
+
2. Select your Geistdocs repository
|
|
36
|
+
3. Configure your project settings:
|
|
37
|
+
- **Framework Preset**: Next.js (automatically detected)
|
|
38
|
+
- **Build Command**: `pnpm build` or `npm run build`
|
|
39
|
+
- **Output Directory**: `.next` (default)
|
|
40
|
+
- **Install Command**: `pnpm install` or `npm install`
|
|
41
|
+
4. Add your environment variables (see [Environment Variables](/docs/env))
|
|
42
|
+
5. Click "Deploy"
|
|
43
|
+
|
|
44
|
+
## Deploy with Vertex-backed Ask AI
|
|
45
|
+
|
|
46
|
+
If your site routes Ask AI through the central Vertex-backed proxy, configure both the Geistdocs site and the Vertex deployment before testing production chat.
|
|
47
|
+
|
|
48
|
+
1. Set `GEISTDOCS_CHAT_PROXY_URL` on the Geistdocs site to the platform proxy URL, including `/vertex`.
|
|
49
|
+
2. Leave `GEISTDOCS_CHAT_PROXY_TOKEN` unset unless your proxy requires bearer authentication.
|
|
50
|
+
3. Add the Geistdocs platform Vercel project as a Trusted Source in the Vertex deployment's Deployment Protection settings.
|
|
51
|
+
4. Confirm the platform proxy can forward the Vercel OIDC token to Vertex in `x-vercel-trusted-oidc-idp-token`.
|
|
52
|
+
|
|
53
|
+
The Geistdocs site does not need Vertex credentials. The platform proxy authenticates to Vertex with Vercel OIDC and Trusted Sources.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Edit on GitHub
|
|
3
|
+
description: Allow readers to contribute directly by editing documentation pages on GitHub
|
|
4
|
+
type: integration
|
|
5
|
+
summary: A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
|
|
6
|
+
url: /docs/edit-on-github
|
|
7
|
+
source: apps/template/content/docs/edit-on-github.mdx
|
|
8
|
+
related:
|
|
9
|
+
- /docs/configuration
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Edit on GitHub
|
|
13
|
+
|
|
14
|
+
The "Edit on GitHub" feature gives readers a direct link to propose documentation changes. This link appears in the table of contents sidebar on every documentation page.
|
|
15
|
+
|
|
16
|
+
Help me configure Edit on GitHub for this Geistdocs site. Check the `github` owner and repo in `geistdocs.tsx`, verify the generated edit URL for this page, and tell me how to disable the action if needed.
|
|
17
|
+
|
|
18
|
+
## How it works
|
|
19
|
+
|
|
20
|
+
When users click the "Edit this page on GitHub" link, they are taken directly to the source file in your GitHub repository. From there, they can:
|
|
21
|
+
|
|
22
|
+
1. Fork the repository (if they haven't already)
|
|
23
|
+
2. Make their edits in the GitHub web editor
|
|
24
|
+
3. Submit a pull request with their changes
|
|
25
|
+
|
|
26
|
+
This workflow leverages GitHub's built-in editing capabilities, making it straightforward for both technical and non-technical users to contribute.
|
|
27
|
+
|
|
28
|
+
## Configuration
|
|
29
|
+
|
|
30
|
+
The Edit on GitHub link is automatically generated based on the `github` object in your `geistdocs.tsx` configuration file. Set the `owner` and `repo` properties to enable this feature:
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
export const github = {
|
|
34
|
+
owner: "your-username",
|
|
35
|
+
repo: "your-repo-name",
|
|
36
|
+
};
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
If these values are not set, the link will not appear on your documentation pages.
|
|
40
|
+
|
|
41
|
+
### Generated URL Format
|
|
42
|
+
|
|
43
|
+
The link follows this pattern:
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
https://github.com/{owner}/{repo}/edit/main/content/docs/{file-path}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
For example, if your page is located at `content/docs/getting-started.mdx`, the generated link would be:
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
https://github.com/your-username/your-repo-name/edit/main/content/docs/getting-started.mdx
|
|
53
|
+
```
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Environment Variables
|
|
3
|
+
description: Learn about the environment variables used in Geistdocs
|
|
4
|
+
type: reference
|
|
5
|
+
summary: Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
|
|
6
|
+
url: /docs/env
|
|
7
|
+
source: apps/template/content/docs/env.mdx
|
|
8
|
+
prerequisites:
|
|
9
|
+
- /docs/getting-started
|
|
10
|
+
related:
|
|
11
|
+
- /docs/configuration
|
|
12
|
+
- /docs/deployment
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Environment Variables
|
|
16
|
+
|
|
17
|
+
Geistdocs uses environment variables to configure Ask AI, optional Vertex-backed proxy mode, and production URL behavior.
|
|
18
|
+
|
|
19
|
+
Review this Geistdocs project and help me configure the required environment variables. Check whether `AI_GATEWAY_API_KEY`, `GEISTDOCS_CHAT_PROXY_URL`, and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` are needed for the features I enabled, then tell me where to set them locally and on Vercel.
|
|
20
|
+
|
|
21
|
+
## `AI_GATEWAY_API_KEY`
|
|
22
|
+
|
|
23
|
+
The API key for the AI Gateway. This is used to power the default local AI chat functionality when `GEISTDOCS_CHAT_PROXY_URL` is not set.
|
|
24
|
+
|
|
25
|
+
> This is automatically set when deploying to Vercel.
|
|
26
|
+
|
|
27
|
+
Leave `GEISTDOCS_CHAT_PROXY_URL` unset to use AI Gateway mode.
|
|
28
|
+
|
|
29
|
+
## `GEISTDOCS_CHAT_PROXY_URL`
|
|
30
|
+
|
|
31
|
+
An optional URL for a chat proxy. When set, Geistdocs searches the local documentation on the first user message, injects the current page and related docs as context, and forwards the request to this proxy.
|
|
32
|
+
|
|
33
|
+
Use this when routing Ask AI through a central Vertex-backed service. The value should point at the Geistdocs platform proxy and include `/vertex`:
|
|
34
|
+
|
|
35
|
+
```txt
|
|
36
|
+
https://<geistdocs-platform-deployment>/vertex
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
When this variable is set, the site does not need `AI_GATEWAY_API_KEY` for Ask AI requests. The platform proxy calls Vertex and forwards a Vercel OIDC token in `x-vercel-trusted-oidc-idp-token` so the Vertex deployment can validate the caller through Deployment Protection Trusted Sources.
|
|
40
|
+
|
|
41
|
+
## `GEISTDOCS_CHAT_PROXY_TOKEN`
|
|
42
|
+
|
|
43
|
+
An optional bearer token for the chat proxy. Only set this if your proxy requires an `Authorization` header.
|
|
44
|
+
|
|
45
|
+
The default Geistdocs platform `/vertex` proxy uses Vercel OIDC and Trusted Sources, so it does not require this token.
|
|
46
|
+
|
|
47
|
+
## Vertex-backed proxy setup
|
|
48
|
+
|
|
49
|
+
To route Ask AI through Vertex:
|
|
50
|
+
|
|
51
|
+
1. Use or deploy the central Geistdocs platform proxy with its `/vertex` route.
|
|
52
|
+
2. In the Vertex deployment's Deployment Protection settings, add the Geistdocs platform Vercel project as a Trusted Source.
|
|
53
|
+
3. In each Geistdocs site that should use Vertex, set `GEISTDOCS_CHAT_PROXY_URL` to the platform proxy URL, including `/vertex`.
|
|
54
|
+
4. Leave `GEISTDOCS_CHAT_PROXY_TOKEN` unset unless you replace the platform proxy with a custom bearer-authenticated proxy.
|
|
55
|
+
|
|
56
|
+
The Vertex deployment does not need a Geistdocs-specific environment variable. Access is controlled by Trusted Sources and the OIDC token forwarded by the platform proxy.
|
|
57
|
+
|
|
58
|
+
## `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`
|
|
59
|
+
|
|
60
|
+
The production URL of the Geistdocs site. This is automatically set when deploying to Vercel.
|
|
61
|
+
|
|
62
|
+
It should be in the format `localhost:3000` (i.e. without the protocol prefix). This is how Vercel sets the environment variable when deploying to a project.
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Feedback
|
|
3
|
+
description: Collect user feedback with an interactive emotion-based widget that creates GitHub Issues
|
|
4
|
+
type: integration
|
|
5
|
+
summary: An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
|
|
6
|
+
url: /docs/feedback
|
|
7
|
+
source: apps/template/content/docs/feedback.mdx
|
|
8
|
+
prerequisites:
|
|
9
|
+
- /docs/getting-started
|
|
10
|
+
related:
|
|
11
|
+
- /docs/provider
|
|
12
|
+
- /docs/configuration
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Feedback
|
|
16
|
+
|
|
17
|
+
The Feedback feature lets readers share page-level feedback through an interactive widget. Feedback is posted to a centralized GitHub repository as issues so your team can track, label, and respond to user input.
|
|
18
|
+
|
|
19
|
+
Help me configure feedback for this Geistdocs project. Check whether feedback is enabled, what `siteId` label is used, and how feedback is sent to the Geistdocs platform and GitHub issues.
|
|
20
|
+
|
|
21
|
+
## How it works
|
|
22
|
+
|
|
23
|
+
The feedback widget appears in the table of contents sidebar on every documentation page. When users click "Give feedback", they can:
|
|
24
|
+
|
|
25
|
+
1. Write their feedback message
|
|
26
|
+
2. Select an emotion that represents their experience (🤩, 🙂, 😕, 😭)
|
|
27
|
+
3. Optionally provide their name and email
|
|
28
|
+
4. Submit their feedback
|
|
29
|
+
|
|
30
|
+
### Feedback Workflow
|
|
31
|
+
|
|
32
|
+
When feedback is submitted:
|
|
33
|
+
|
|
34
|
+
1. The feedback is validated against a JSON schema
|
|
35
|
+
2. A new GitHub Issue is created in the configured feedback repository
|
|
36
|
+
3. Labels are automatically applied based on the emotion, topic, and other metadata
|
|
37
|
+
4. User details and metadata are formatted into a structured markdown table
|
|
38
|
+
|
|
39
|
+
Each piece of feedback creates a separate issue, allowing for individual tracking and resolution.
|
|
40
|
+
|
|
41
|
+
## Feedback Schema
|
|
42
|
+
|
|
43
|
+
The API accepts the following fields:
|
|
44
|
+
|
|
45
|
+
| Field | Type | Required | Max Length | Description |
|
|
46
|
+
| --------- | ------ | -------- | ---------- | ------------------------------------- |
|
|
47
|
+
| `note` | string | Yes | 16,384 | The feedback message |
|
|
48
|
+
| `url` | string | No | 1,024 | Page URL where feedback was submitted |
|
|
49
|
+
| `emotion` | string | No | 1 | Emoji representing user sentiment |
|
|
50
|
+
| `topic` | string | No | 1,024 | Feedback topic/category |
|
|
51
|
+
| `name` | string | No | 1,024 | User's name |
|
|
52
|
+
| `email` | string | No | 1,024 | User's email |
|
|
53
|
+
| `ua` | string | No | 256 | User agent string |
|
|
54
|
+
| `label` | string | No | 64 | Custom label for the issue |
|
|
55
|
+
| `thumbs` | string | No | 4 | Thumbs up/down indicator |
|
|
56
|
+
| `reason` | string | No | 10 | Reason for thumbs down |
|
|
57
|
+
| `plan` | string | No | 10 | User's plan type |
|
|
58
|
+
|
|
59
|
+
Additional fields are captured as metadata and displayed in the issue body.
|
|
60
|
+
|
|
61
|
+
## Features
|
|
62
|
+
|
|
63
|
+
### Automatic Labeling
|
|
64
|
+
|
|
65
|
+
Issues are automatically labeled based on:
|
|
66
|
+
|
|
67
|
+
- **Emotion**: `emotion-amazed`, `emotion-happy`, `emotion-sad`, `emotion-cry`
|
|
68
|
+
- **Topic**: `topic-{topic-name}`
|
|
69
|
+
- **Plan**: `{plan}-plan`
|
|
70
|
+
- **Thumbs**: `thumbs-up`, `thumbs-down`
|
|
71
|
+
- **Reason**: `reason-{reason}` (for thumbs down)
|
|
72
|
+
- **Custom labels**: Any label passed via the `label` field
|
|
73
|
+
- **Default labels**: `unresolved`, `vercel-site`
|
|
74
|
+
|
|
75
|
+
### Structured Issue Body
|
|
76
|
+
|
|
77
|
+
Each issue includes a formatted markdown body with:
|
|
78
|
+
|
|
79
|
+
- The feedback note
|
|
80
|
+
- URL where feedback was submitted
|
|
81
|
+
- User details table (email, context, IP, user agent)
|
|
82
|
+
- Metadata table for any additional fields
|
|
83
|
+
|
|
84
|
+
### Metadata Support
|
|
85
|
+
|
|
86
|
+
Pass any additional fields in the request body, and they are captured as metadata and displayed in a separate table in the issue. This allows you to include:
|
|
87
|
+
|
|
88
|
+
- User IDs
|
|
89
|
+
- Feature flags
|
|
90
|
+
- Experiment groups
|
|
91
|
+
- Custom tracking data
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Getting Started
|
|
3
|
+
description: Create a Geistdocs project and start writing documentation
|
|
4
|
+
type: guide
|
|
5
|
+
summary: Create a Geistdocs project, run it locally, and edit your first documentation page.
|
|
6
|
+
url: /docs/getting-started
|
|
7
|
+
source: apps/template/content/docs/getting-started.mdx
|
|
8
|
+
related:
|
|
9
|
+
- /docs/configuration
|
|
10
|
+
- /docs/migration
|
|
11
|
+
- /docs/syntax
|
|
12
|
+
- /docs/deployment
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Getting Started
|
|
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.
|
|
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`.
|
|
20
|
+
|
|
21
|
+
## Prerequisites
|
|
22
|
+
|
|
23
|
+
Before you begin, install:
|
|
24
|
+
|
|
25
|
+
- Node.js 18 or later
|
|
26
|
+
- pnpm, npm, or another package manager
|
|
27
|
+
- Git
|
|
28
|
+
|
|
29
|
+
## Create a project
|
|
30
|
+
|
|
31
|
+
Run the Geistdocs CLI from an empty parent folder:
|
|
32
|
+
|
|
33
|
+
```bash title="Terminal"
|
|
34
|
+
pnpm dlx @vercel/geistdocs init --name my-docs
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
You can also use npm:
|
|
38
|
+
|
|
39
|
+
```bash title="Terminal"
|
|
40
|
+
npx @vercel/geistdocs init --name my-docs
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
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
|
+
|
|
45
|
+
## Understand generated dependencies
|
|
46
|
+
|
|
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.
|
|
48
|
+
|
|
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.
|
|
50
|
+
|
|
51
|
+
## Start the development server
|
|
52
|
+
|
|
53
|
+
Open the generated project and start Next.js:
|
|
54
|
+
|
|
55
|
+
```bash title="Terminal"
|
|
56
|
+
cd my-docs
|
|
57
|
+
pnpm dev
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Open `http://localhost:3000` in your browser.
|
|
61
|
+
|
|
62
|
+
## Edit your first page
|
|
63
|
+
|
|
64
|
+
Docs live in `content/docs`. Edit the overview page:
|
|
65
|
+
|
|
66
|
+
```mdx title="content/docs/index.mdx"
|
|
67
|
+
---
|
|
68
|
+
title: Overview
|
|
69
|
+
description: Learn how to use my project.
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
My project helps developers build with clear documentation.
|
|
73
|
+
|
|
74
|
+
## Start here
|
|
75
|
+
|
|
76
|
+
Add the first workflow you want readers to complete.
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Add more pages by creating new `.mdx` files in `content/docs`.
|
|
80
|
+
|
|
81
|
+
## Update the sidebar
|
|
82
|
+
|
|
83
|
+
Use `content/docs/meta.json` to control page order and groups:
|
|
84
|
+
|
|
85
|
+
```json title="content/docs/meta.json"
|
|
86
|
+
{
|
|
87
|
+
"title": "Documentation",
|
|
88
|
+
"root": true,
|
|
89
|
+
"pages": ["index", "getting-started", "---Guides---", "deploy"]
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Configure the site
|
|
94
|
+
|
|
95
|
+
Use `geistdocs.tsx` to customize the site shell:
|
|
96
|
+
|
|
97
|
+
```tsx title="geistdocs.tsx"
|
|
98
|
+
export const title = "My Documentation";
|
|
99
|
+
|
|
100
|
+
export const nav = [
|
|
101
|
+
{ label: "Docs", href: "/docs" },
|
|
102
|
+
{ label: "GitHub", href: "https://github.com/my-org/my-repo" },
|
|
103
|
+
];
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Read [Configuration](/docs/configuration) for the full configuration surface.
|
|
107
|
+
|
|
108
|
+
## Update Geistdocs
|
|
109
|
+
|
|
110
|
+
For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files.
|
|
111
|
+
|
|
112
|
+
```bash title="Terminal"
|
|
113
|
+
pnpm exec geistdocs update
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Review and test dependency changes before committing.
|