@vercel/geistdocs 1.3.0 → 1.4.0

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 (50) hide show
  1. package/dist/assets/logos/logo-svelte-kit.d.ts +0 -3
  2. package/dist/assets/logos/logo-svelte-kit.d.ts.map +1 -1
  3. package/dist/assets/logos/logo-svelte-kit.js +2 -5
  4. package/dist/cli/index.js +1 -1
  5. package/dist/config.d.ts +6 -0
  6. package/dist/config.d.ts.map +1 -1
  7. package/dist/routes/agents.d.ts.map +1 -1
  8. package/dist/routes/agents.js +14 -29
  9. package/dist/routes/discovery.d.ts +14 -0
  10. package/dist/routes/discovery.d.ts.map +1 -0
  11. package/dist/routes/discovery.js +74 -0
  12. package/dist/routes/mcp.d.ts +26 -0
  13. package/dist/routes/mcp.d.ts.map +1 -0
  14. package/dist/routes/mcp.js +31 -0
  15. package/dist/source.d.ts +1 -1
  16. package/dist/source.d.ts.map +1 -1
  17. package/dist/source.js +4 -1
  18. package/docs/agents.md +44 -0
  19. package/docs/llms.txt +2965 -0
  20. package/docs/manifest.json +194 -0
  21. package/docs/pages/agent-readiness.md +141 -0
  22. package/docs/pages/ask-ai.md +143 -0
  23. package/docs/pages/configuration.md +278 -0
  24. package/docs/pages/deployment.md +53 -0
  25. package/docs/pages/edit-on-github.md +53 -0
  26. package/docs/pages/env.md +62 -0
  27. package/docs/pages/feedback.md +91 -0
  28. package/docs/pages/getting-started.md +116 -0
  29. package/docs/pages/index.md +99 -0
  30. package/docs/pages/internationalization.md +124 -0
  31. package/docs/pages/llms-txt.md +88 -0
  32. package/docs/pages/md.md +84 -0
  33. package/docs/pages/migration.md +376 -0
  34. package/docs/pages/open-in-chat.md +82 -0
  35. package/docs/pages/provider.md +76 -0
  36. package/docs/pages/proxy.md +180 -0
  37. package/docs/pages/rss.md +110 -0
  38. package/docs/pages/syntax.md +413 -0
  39. package/docs/pages/theme-aware-image.md +59 -0
  40. package/docs/pages/versioned-docs.md +230 -0
  41. package/docs/sitemap.md +25 -0
  42. package/package.json +12 -2
  43. package/template/AGENTS.md +10 -3
  44. package/template/app/[lang]/.well-known/mcp.json/route.ts +8 -0
  45. package/template/content/docs/agent-readiness.mdx +44 -8
  46. package/template/content/docs/configuration.mdx +1 -0
  47. package/template/content/docs/index.mdx +1 -1
  48. package/template/content/docs/llms-txt.mdx +1 -1
  49. package/template/content/docs/migration.mdx +12 -2
  50. 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.