@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.
- package/dist/assets/logos/logo-svelte-kit.d.ts +0 -3
- package/dist/assets/logos/logo-svelte-kit.d.ts.map +1 -1
- package/dist/assets/logos/logo-svelte-kit.js +2 -5
- 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/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,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Theme-Aware Image
|
|
3
|
+
description: Display different images based on the user's light or dark theme preference
|
|
4
|
+
type: reference
|
|
5
|
+
summary: A component that swaps images based on the active theme, built on top of Next.js Image.
|
|
6
|
+
url: /docs/theme-aware-image
|
|
7
|
+
source: apps/template/content/docs/theme-aware-image.mdx
|
|
8
|
+
prerequisites:
|
|
9
|
+
- /docs/getting-started
|
|
10
|
+
- /docs/provider
|
|
11
|
+
related:
|
|
12
|
+
- /docs/syntax
|
|
13
|
+
- /docs/configuration
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Theme-Aware Image
|
|
17
|
+
|
|
18
|
+
The `ThemeAwareImage` component renders different images depending on whether the user is viewing your documentation in light or dark mode. It extends the Next.js `Image` component, so you get all the same optimization benefits like lazy loading, responsive sizing, and format conversion.
|
|
19
|
+
|
|
20
|
+
Help me add a theme-aware image to a Geistdocs MDX page. Create a usage example with light and dark image sources, alt text, width, and height, then explain where to place the image files.
|
|
21
|
+
|
|
22
|
+
## Usage
|
|
23
|
+
|
|
24
|
+
Import the component and pass a `src` object with `light` and `dark` variants:
|
|
25
|
+
|
|
26
|
+
```tsx
|
|
27
|
+
import { ThemeAwareImage } from "@vercel/geistdocs/components/theme-aware-image";
|
|
28
|
+
|
|
29
|
+
<ThemeAwareImage
|
|
30
|
+
src={{
|
|
31
|
+
light: "/images/diagram-light.png",
|
|
32
|
+
dark: "/images/diagram-dark.png",
|
|
33
|
+
}}
|
|
34
|
+
alt="Architecture diagram"
|
|
35
|
+
width={800}
|
|
36
|
+
height={400}
|
|
37
|
+
/>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The component reads the current theme from `next-themes` and resolves the correct image source automatically. All standard Next.js `Image` props (such as `width`, `height`, `alt`, `priority`, and `className`) are supported.
|
|
41
|
+
|
|
42
|
+
## How it works
|
|
43
|
+
|
|
44
|
+
`ThemeAwareImage` uses the `resolvedTheme` value from the `useTheme` hook provided by `next-themes`. This ensures it responds to the actual rendered theme, even when the user's preference is set to "system".
|
|
45
|
+
|
|
46
|
+
- When `resolvedTheme` is `"dark"`, the `src.dark` image is displayed.
|
|
47
|
+
- Otherwise, the `src.light` image is used.
|
|
48
|
+
|
|
49
|
+
Because this component relies on client-side theme detection, it is a client component (`"use client"`).
|
|
50
|
+
|
|
51
|
+
## Props
|
|
52
|
+
|
|
53
|
+
| Prop | Type | Description |
|
|
54
|
+
| --- | --- | --- |
|
|
55
|
+
| `src` | `{ light: ImageProps["src"]; dark: ImageProps["src"] }` | An object containing the light and dark image sources |
|
|
56
|
+
| `alt` | `string` | Accessible alt text for the image |
|
|
57
|
+
| `width` | `number` | The width of the image in pixels |
|
|
58
|
+
| `height` | `number` | The height of the image in pixels |
|
|
59
|
+
| `...rest` | `ImageProps` | Any additional props supported by the Next.js `Image` component |
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Versioned docs
|
|
3
|
+
description: Configure multiple documentation versions with package-backed source helpers
|
|
4
|
+
type: guide
|
|
5
|
+
summary: Use createVersionedSources to configure stable, pre-release, or host-based documentation versions.
|
|
6
|
+
url: /docs/versioned-docs
|
|
7
|
+
source: apps/template/content/docs/versioned-docs.mdx
|
|
8
|
+
prerequisites:
|
|
9
|
+
- /docs/configuration
|
|
10
|
+
related:
|
|
11
|
+
- /docs/proxy
|
|
12
|
+
- /docs/llms-txt
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Versioned docs
|
|
16
|
+
|
|
17
|
+
Versioned docs let you serve multiple documentation sets from one Geistdocs project. Use them for stable and pre-release docs, previous major versions, or host-based version switching.
|
|
18
|
+
|
|
19
|
+
Help me add versioned docs to this Geistdocs site. Inspect `source.config.ts`, `lib/geistdocs/source.ts`, app route files, and the docs layout, then propose a versioned source setup using `createVersionedSources`.
|
|
20
|
+
|
|
21
|
+
## Configure source collections
|
|
22
|
+
|
|
23
|
+
Create one Fumadocs collection for each version in `source.config.ts`:
|
|
24
|
+
|
|
25
|
+
```ts title="source.config.ts"
|
|
26
|
+
import {
|
|
27
|
+
defineGeistdocsSourceConfig,
|
|
28
|
+
geistdocsFrontmatterSchema,
|
|
29
|
+
} from "@vercel/geistdocs/source-config";
|
|
30
|
+
import { defineDocs } from "fumadocs-mdx/config";
|
|
31
|
+
|
|
32
|
+
export const v4docs = defineDocs({
|
|
33
|
+
dir: "content/docs/v4",
|
|
34
|
+
docs: {
|
|
35
|
+
schema: geistdocsFrontmatterSchema,
|
|
36
|
+
postprocess: {
|
|
37
|
+
includeProcessedMarkdown: true,
|
|
38
|
+
},
|
|
39
|
+
},
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
export const v5docs = defineDocs({
|
|
43
|
+
dir: "content/docs/v5",
|
|
44
|
+
docs: {
|
|
45
|
+
schema: geistdocsFrontmatterSchema,
|
|
46
|
+
postprocess: {
|
|
47
|
+
includeProcessedMarkdown: true,
|
|
48
|
+
},
|
|
49
|
+
},
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
export default defineGeistdocsSourceConfig();
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Create versioned sources
|
|
56
|
+
|
|
57
|
+
Use `createVersionedSources` in `lib/geistdocs/source.ts`:
|
|
58
|
+
|
|
59
|
+
```ts title="lib/geistdocs/source.ts"
|
|
60
|
+
import { createVersionedSources } from "@vercel/geistdocs/source";
|
|
61
|
+
import { v4docs, v5docs } from "@/.source/server";
|
|
62
|
+
import { config } from "./config";
|
|
63
|
+
|
|
64
|
+
export const versions = createVersionedSources({
|
|
65
|
+
config,
|
|
66
|
+
current: "v4",
|
|
67
|
+
versions: [
|
|
68
|
+
{
|
|
69
|
+
id: "v4",
|
|
70
|
+
label: "v4",
|
|
71
|
+
docs: v4docs,
|
|
72
|
+
baseUrl: "/docs",
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
id: "v5",
|
|
76
|
+
label: "v5 pre-release",
|
|
77
|
+
docs: v5docs,
|
|
78
|
+
baseUrl: "/docs",
|
|
79
|
+
routePrefix: "/v5",
|
|
80
|
+
},
|
|
81
|
+
],
|
|
82
|
+
});
|
|
83
|
+
|
|
84
|
+
export const geistdocsSource = versions.current;
|
|
85
|
+
export const source = geistdocsSource.source;
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
The returned object includes:
|
|
89
|
+
|
|
90
|
+
| Property | Type | Description |
|
|
91
|
+
| --- | --- | --- |
|
|
92
|
+
| `current` | `GeistdocsSourceBundle` | The source matching the `current` version ID. |
|
|
93
|
+
| `byId` | `Record<string, GeistdocsSourceBundle>` | A map of version IDs to source bundles. |
|
|
94
|
+
| `all` | `Array` | Version metadata and source bundles for rendering UI. |
|
|
95
|
+
| `currentVersion` | `string` | The active version ID. |
|
|
96
|
+
|
|
97
|
+
## Render versioned pages
|
|
98
|
+
|
|
99
|
+
Use the current version for `/docs` and a specific version for version-prefixed routes:
|
|
100
|
+
|
|
101
|
+
```tsx title="app/[lang]/docs/[[...slug]]/page.tsx"
|
|
102
|
+
import { createDocsPage } from "@vercel/geistdocs/pages/docs";
|
|
103
|
+
import { config } from "@/lib/geistdocs/config";
|
|
104
|
+
import { versions } from "@/lib/geistdocs/source";
|
|
105
|
+
|
|
106
|
+
const docsPage = createDocsPage({
|
|
107
|
+
config,
|
|
108
|
+
source: versions.current,
|
|
109
|
+
});
|
|
110
|
+
|
|
111
|
+
export default docsPage.Page;
|
|
112
|
+
export const generateStaticParams = docsPage.generateStaticParams;
|
|
113
|
+
export const generateMetadata = docsPage.generateMetadata;
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
```tsx title="app/[lang]/v5/docs/[[...slug]]/page.tsx"
|
|
117
|
+
import { createDocsPage } from "@vercel/geistdocs/pages/docs";
|
|
118
|
+
import { config } from "@/lib/geistdocs/config";
|
|
119
|
+
import { versions } from "@/lib/geistdocs/source";
|
|
120
|
+
|
|
121
|
+
const docsPage = createDocsPage({
|
|
122
|
+
config,
|
|
123
|
+
source: versions.byId.v5,
|
|
124
|
+
getPageUrl: ({ page }) => `/v5${page.url}`,
|
|
125
|
+
metadata: ({ metadata }) => ({
|
|
126
|
+
...metadata,
|
|
127
|
+
robots: {
|
|
128
|
+
index: false,
|
|
129
|
+
follow: true,
|
|
130
|
+
},
|
|
131
|
+
}),
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
export default docsPage.Page;
|
|
135
|
+
export const generateStaticParams = docsPage.generateStaticParams;
|
|
136
|
+
export const generateMetadata = docsPage.generateMetadata;
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Use `getPageUrl` when the route path differs from the source `baseUrl`. This keeps page actions and markdown links pointed at the public URL.
|
|
140
|
+
|
|
141
|
+
## Add a version selector
|
|
142
|
+
|
|
143
|
+
Use `GeistdocsVersionSelect` when readers need to move between versions:
|
|
144
|
+
|
|
145
|
+
```tsx title="components/geistdocs/docs-layout.tsx"
|
|
146
|
+
import { GeistdocsDocsLayout } from "@vercel/geistdocs/layout";
|
|
147
|
+
import { GeistdocsVersionSelect } from "@vercel/geistdocs/versions";
|
|
148
|
+
import { config } from "@/lib/geistdocs/config";
|
|
149
|
+
|
|
150
|
+
export const DocsLayout = ({ tree, children }: DocsLayoutProps) => (
|
|
151
|
+
<GeistdocsDocsLayout
|
|
152
|
+
config={config}
|
|
153
|
+
sidebarTop={
|
|
154
|
+
<GeistdocsVersionSelect
|
|
155
|
+
current="v4"
|
|
156
|
+
versions={[
|
|
157
|
+
{ id: "v4", label: "v4" },
|
|
158
|
+
{ id: "v5", label: "v5 pre-release", routePrefix: "/v5" },
|
|
159
|
+
]}
|
|
160
|
+
/>
|
|
161
|
+
}
|
|
162
|
+
tree={tree}
|
|
163
|
+
>
|
|
164
|
+
{children}
|
|
165
|
+
</GeistdocsDocsLayout>
|
|
166
|
+
);
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Each version can define an `icon` to override the default current/previous version icons:
|
|
170
|
+
|
|
171
|
+
```tsx
|
|
172
|
+
<GeistdocsVersionSelect
|
|
173
|
+
current="v6"
|
|
174
|
+
versions={[
|
|
175
|
+
{ id: "v6", label: "v6 latest", icon: <span>6</span> },
|
|
176
|
+
{ id: "v5", label: "v5", icon: <span>5</span>, routePrefix: "/v5" },
|
|
177
|
+
]}
|
|
178
|
+
/>
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Use `GeistdocsRouteSelect` for framework, product, or route switchers that should not use version-specific labels:
|
|
182
|
+
|
|
183
|
+
```tsx
|
|
184
|
+
import { LogoNextjs, LogoSvelteKit } from "@vercel/geistdocs/assets/logos";
|
|
185
|
+
import { GeistdocsRouteSelect } from "@vercel/geistdocs/versions";
|
|
186
|
+
|
|
187
|
+
<GeistdocsRouteSelect
|
|
188
|
+
ariaLabel="Select framework"
|
|
189
|
+
current="nextjs"
|
|
190
|
+
items={[
|
|
191
|
+
{
|
|
192
|
+
id: "nextjs",
|
|
193
|
+
label: "Next.js",
|
|
194
|
+
description: "React framework",
|
|
195
|
+
icon: <LogoNextjs height={18} />,
|
|
196
|
+
href: "/:path*",
|
|
197
|
+
},
|
|
198
|
+
{
|
|
199
|
+
id: "sveltekit",
|
|
200
|
+
label: "SvelteKit",
|
|
201
|
+
description: "Svelte framework",
|
|
202
|
+
icon: <LogoSvelteKit height={18} />,
|
|
203
|
+
routePrefix: "/sveltekit",
|
|
204
|
+
href: "/sveltekit/:path*",
|
|
205
|
+
},
|
|
206
|
+
]}
|
|
207
|
+
/>
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
For host-based versions, use `href` instead of `routePrefix`:
|
|
211
|
+
|
|
212
|
+
```tsx
|
|
213
|
+
<GeistdocsVersionSelect
|
|
214
|
+
current="v6"
|
|
215
|
+
versions={[
|
|
216
|
+
{ id: "v6", label: "v6 latest" },
|
|
217
|
+
{ id: "v5", label: "v5", href: "https://v5.example.com/:path*" },
|
|
218
|
+
{ id: "v4", label: "v4", href: "https://v4.example.com/:path*" },
|
|
219
|
+
]}
|
|
220
|
+
/>
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## Configure markdown routes
|
|
224
|
+
|
|
225
|
+
Each public route family needs a matching markdown route in `proxy.ts`. Read [Proxy and markdown routes](/docs/proxy) for the proxy configuration.
|
|
226
|
+
|
|
227
|
+
## Next steps
|
|
228
|
+
|
|
229
|
+
- Read [Proxy and markdown routes](/docs/proxy) to connect versioned pages to `.md`, `.mdx`, and AI-agent rewrites.
|
|
230
|
+
- Read [llms.txt](/docs/llms-txt) to configure all-docs markdown output for multiple sources.
|
package/docs/sitemap.md
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Geistdocs Documentation Sitemap
|
|
2
|
+
|
|
3
|
+
This file maps the documentation bundled with `@vercel/geistdocs`.
|
|
4
|
+
Use it to choose focused page files from `docs/pages/` before reading the full `llms.txt` bundle.
|
|
5
|
+
|
|
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
|
+
- [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
|
+
- [Environment Variables](pages/env.md) | URL: /docs/env | Type: reference | Summary: Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
|
|
9
|
+
- [Deploy to Vercel](pages/deployment.md) | URL: /docs/deployment | Type: guide | Summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
|
|
10
|
+
- [Migration guide](pages/migration.md) | URL: /docs/migration | Type: guide | Summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
|
|
11
|
+
- [Configuration](pages/configuration.md) | URL: /docs/configuration | Type: reference | Summary: Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
|
|
12
|
+
- [Syntax](pages/syntax.md) | URL: /docs/syntax | Type: reference | Summary: Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
|
|
13
|
+
- [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.
|
|
14
|
+
- [Versioned docs](pages/versioned-docs.md) | URL: /docs/versioned-docs | Type: guide | Summary: Use createVersionedSources to configure stable, pre-release, or host-based documentation versions.
|
|
15
|
+
- [Proxy and markdown routes](pages/proxy.md) | URL: /docs/proxy | Type: reference | Summary: Configure createProxy with before and after hooks, markdown route mappings, and a static Next.js matcher.
|
|
16
|
+
- [.md Extension](pages/md.md) | URL: /docs/md | Type: conceptual | Summary: Access any documentation page as raw Markdown by appending .md or .mdx to the URL for AI tool consumption.
|
|
17
|
+
- [Agent readiness](pages/agent-readiness.md) | URL: /docs/agent-readiness | Type: guide | Summary: Generate /agents.md and /.well-known/mcp.json from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
|
|
18
|
+
- [Ask AI](pages/ask-ai.md) | URL: /docs/ask-ai | Type: conceptual | Summary: An AI-powered chat assistant with context-aware search, persistent history, and suggested prompts for your documentation.
|
|
19
|
+
- [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.
|
|
20
|
+
- [Feedback](pages/feedback.md) | URL: /docs/feedback | Type: integration | Summary: An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
|
|
21
|
+
- [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.
|
|
22
|
+
- [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.
|
|
23
|
+
- [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.
|
|
24
|
+
- [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.
|
|
25
|
+
- [Theme-Aware Image](pages/theme-aware-image.md) | URL: /docs/theme-aware-image | Type: reference | Summary: A component that swaps images based on the active theme, built on top of Next.js Image.
|
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.
|
|
4
|
+
"version": "1.4.0",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
7
7
|
"url": "https://github.com/vercel/geistdocs",
|
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
],
|
|
17
17
|
"files": [
|
|
18
18
|
"dist",
|
|
19
|
+
"docs",
|
|
19
20
|
"source-config.js",
|
|
20
21
|
"template",
|
|
21
22
|
"styles.css"
|
|
@@ -85,6 +86,10 @@
|
|
|
85
86
|
"types": "./dist/routes/agents.d.ts",
|
|
86
87
|
"default": "./dist/routes/agents.js"
|
|
87
88
|
},
|
|
89
|
+
"./routes/mcp": {
|
|
90
|
+
"types": "./dist/routes/mcp.d.ts",
|
|
91
|
+
"default": "./dist/routes/mcp.js"
|
|
92
|
+
},
|
|
88
93
|
"./proxy": {
|
|
89
94
|
"types": "./dist/proxy.d.ts",
|
|
90
95
|
"default": "./dist/proxy.js"
|
|
@@ -97,6 +102,11 @@
|
|
|
97
102
|
"types": "./dist/source-config.d.ts",
|
|
98
103
|
"default": "./source-config.js"
|
|
99
104
|
},
|
|
105
|
+
"./docs/agents.md": "./docs/agents.md",
|
|
106
|
+
"./docs/llms.txt": "./docs/llms.txt",
|
|
107
|
+
"./docs/manifest.json": "./docs/manifest.json",
|
|
108
|
+
"./docs/pages/*": "./docs/pages/*",
|
|
109
|
+
"./docs/sitemap.md": "./docs/sitemap.md",
|
|
100
110
|
"./shiki-theme": {
|
|
101
111
|
"types": "./dist/shiki-theme.d.ts",
|
|
102
112
|
"default": "./dist/shiki-theme.js"
|
|
@@ -276,6 +286,6 @@
|
|
|
276
286
|
"typescript": "^5.9.3"
|
|
277
287
|
},
|
|
278
288
|
"scripts": {
|
|
279
|
-
"build": "rm -rf dist template && node ./scripts/bundle-template.mjs && tsc -p tsconfig.runtime.json && tsup --config tsup.config.cli.ts"
|
|
289
|
+
"build": "rm -rf dist docs template && node ./scripts/bundle-template.mjs && node ./scripts/bundle-docs.mjs && tsc -p tsconfig.runtime.json && tsup --config tsup.config.cli.ts"
|
|
280
290
|
}
|
|
281
291
|
}
|
package/template/AGENTS.md
CHANGED
|
@@ -13,6 +13,13 @@ Use these instructions when an AI coding agent edits this project.
|
|
|
13
13
|
- Do not deep import from `@vercel/geistdocs/dist` or edit files in `node_modules/@vercel/geistdocs`.
|
|
14
14
|
- Do not edit generated directories such as `.source/`, `.next/`, `node_modules/`, or build output.
|
|
15
15
|
|
|
16
|
+
## Package Docs For Agents
|
|
17
|
+
|
|
18
|
+
- When package API behavior is unclear, read the installed package docs in `node_modules/@vercel/geistdocs/docs` before guessing.
|
|
19
|
+
- Start with `node_modules/@vercel/geistdocs/docs/agents.md` and `node_modules/@vercel/geistdocs/docs/sitemap.md` to identify the relevant focused page.
|
|
20
|
+
- Use `node_modules/@vercel/geistdocs/docs/pages/*.md` for task-specific guidance and `node_modules/@vercel/geistdocs/docs/llms.txt` only when you need broad package context.
|
|
21
|
+
- These package docs are read-only generated artifacts. Do not edit files under `node_modules/@vercel/geistdocs`; change local adapter files or update the package instead.
|
|
22
|
+
|
|
16
23
|
## Common edit targets
|
|
17
24
|
|
|
18
25
|
| Task | Edit |
|
|
@@ -26,7 +33,7 @@ Use these instructions when an AI coding agent edits this project.
|
|
|
26
33
|
| Configure the Fumadocs source adapter or versioned docs | `lib/geistdocs/source.ts` |
|
|
27
34
|
| Configure Fumadocs collections and source-safe MDX processing | `source.config.ts` |
|
|
28
35
|
| Configure the docs page renderer | `app/[lang]/docs/[[...slug]]/page.tsx` |
|
|
29
|
-
| Configure AI-readable markdown output | `app/[lang]/llms.txt/route.ts`, `app/[lang]/llms.mdx/[[...slug]]/route.ts`, `app/[lang]/sitemap.md/route.ts` |
|
|
36
|
+
| Configure AI-readable markdown output | `app/[lang]/agents.md/route.ts`, `app/[lang]/.well-known/mcp.json/route.ts`, `app/[lang]/llms.txt/route.ts`, `app/[lang]/llms.mdx/[[...slug]]/route.ts`, `app/[lang]/sitemap.md/route.ts` |
|
|
30
37
|
| Configure chat or search APIs | `app/api/chat/route.ts`, `app/api/search/route.ts` |
|
|
31
38
|
| Add request handling before or after Geistdocs routing | `proxy.ts` |
|
|
32
39
|
| Edit the marketing home page | `app/[lang]/(home)/**` |
|
|
@@ -46,7 +53,7 @@ Use these instructions when an AI coding agent edits this project.
|
|
|
46
53
|
- Keep App Router route files as thin adapters around package helpers such as `createDocsPage`, `createChatRoute`, `createLlmsRoute`, and `createProxy`.
|
|
47
54
|
- Keep `export const config` in `proxy.ts` as a static object. Next.js must parse proxy matchers at build time.
|
|
48
55
|
- Use proxy matcher exclusions that only match `/api` and `/api/...`, such as `api(?:/|$)`. Do not exclude broad prefixes like `api`, because that also excludes routes such as `/api-reference`.
|
|
49
|
-
- Preserve markdown negotiation unless the task explicitly changes AI-readable output. Geistdocs serves `/llms.txt
|
|
56
|
+
- Preserve markdown negotiation unless the task explicitly changes AI-readable output. Geistdocs serves `/agents.md`, `/llms.txt`, `/.well-known/mcp.json`, and per-page Markdown for `.md`, `.mdx`, `Accept: text/markdown`, and AI-agent requests.
|
|
50
57
|
- When adding custom proxy behavior, prefer `before`, `after`, and `markdownRoutes` options on `createProxy` instead of replacing the proxy.
|
|
51
58
|
- Use explicit `markdownRoutes` for root-mounted docs or any site where homepage/app routes coexist with docs routes.
|
|
52
59
|
|
|
@@ -91,5 +98,5 @@ Use these instructions when an AI coding agent edits this project.
|
|
|
91
98
|
|
|
92
99
|
- Run `pnpm build` after changing routes, config, source setup, MDX components, or package versions.
|
|
93
100
|
- Run `pnpm dev` and open the changed pages when visual layout, navigation, or MDX rendering changes.
|
|
94
|
-
- Check both `/docs` and AI-readable routes such as `/llms.txt
|
|
101
|
+
- Check both `/docs` and AI-readable routes such as `/agents.md`, `/.well-known/mcp.json`, `/llms.txt`, or a page-level `.md` URL when changing content routing or proxy behavior.
|
|
95
102
|
- Confirm no secrets were added to source files. Use `.env.local` for local values and keep it out of Git.
|
|
@@ -1,23 +1,23 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Agent readiness
|
|
3
|
-
description: Expose
|
|
3
|
+
description: Expose agents.md and MCP discovery files that help AI agents discover and use your docs site
|
|
4
4
|
type: guide
|
|
5
|
-
summary: Generate /agents.md from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
|
|
5
|
+
summary: Generate /agents.md and /.well-known/mcp.json from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
|
|
6
6
|
related:
|
|
7
7
|
- /docs/llms-txt
|
|
8
8
|
- /docs/md
|
|
9
9
|
- /docs/proxy
|
|
10
10
|
---
|
|
11
11
|
|
|
12
|
-
Geistdocs can generate `/agents.md
|
|
12
|
+
Geistdocs can generate `/agents.md` and `/.well-known/mcp.json` discovery files from your site config. These files tell AI agents where your docs live and which machine-readable integration surfaces your product declares.
|
|
13
13
|
|
|
14
|
-
<CopyPrompt text="Review this Geistdocs site's /agents.md
|
|
15
|
-
Review this Geistdocs site's `/agents.md`
|
|
14
|
+
<CopyPrompt text="Review this Geistdocs site's /agents.md and /.well-known/mcp.json files. Check whether they list the product description, documentation links, llms.txt, sitemap.md, OpenAPI specs, and MCP servers accurately.">
|
|
15
|
+
Review this Geistdocs site's `/agents.md` and `/.well-known/mcp.json` files. Check whether they list the product description, documentation links, `llms.txt`, `sitemap.md`, OpenAPI specs, and MCP servers accurately.
|
|
16
16
|
</CopyPrompt>
|
|
17
17
|
|
|
18
18
|
## What it provides
|
|
19
19
|
|
|
20
|
-
The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation.
|
|
20
|
+
The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. The optional `/.well-known/mcp.json` route advertises configured MCP servers without running an MCP server inside Geistdocs.
|
|
21
21
|
|
|
22
22
|
It can include:
|
|
23
23
|
|
|
@@ -45,6 +45,35 @@ export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
|
|
|
45
45
|
|
|
46
46
|
Because the route is under `[lang]`, the Geistdocs proxy can serve `/agents.md` through the default language route.
|
|
47
47
|
|
|
48
|
+
Generated projects also include a thin adapter for MCP discovery:
|
|
49
|
+
|
|
50
|
+
```ts title="app/[lang]/.well-known/mcp.json/route.ts"
|
|
51
|
+
import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
|
|
52
|
+
import { config } from "@/lib/geistdocs/config";
|
|
53
|
+
|
|
54
|
+
export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
|
|
55
|
+
config,
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The MCP discovery route returns `404` until you configure `agent.mcp.servers`, so generated sites do not claim MCP support by default.
|
|
60
|
+
|
|
61
|
+
When configured, `/.well-known/mcp.json` returns the declared MCP servers:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"name": "My Product",
|
|
66
|
+
"description": "My Product helps teams build and deploy applications.",
|
|
67
|
+
"servers": [
|
|
68
|
+
{
|
|
69
|
+
"name": "My Product MCP",
|
|
70
|
+
"url": "https://example.com/api/mcp",
|
|
71
|
+
"description": "Use product tools through MCP."
|
|
72
|
+
}
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
48
77
|
## Configure agent metadata
|
|
49
78
|
|
|
50
79
|
Add agent-readiness metadata in `geistdocs.tsx`, then pass it through `defineConfig` in `lib/geistdocs/config.tsx`.
|
|
@@ -62,6 +91,13 @@ export const agent = {
|
|
|
62
91
|
},
|
|
63
92
|
api: {
|
|
64
93
|
openApiUrl: "https://api.example.com/openapi.json",
|
|
94
|
+
openApiSpecs: [
|
|
95
|
+
{
|
|
96
|
+
label: "Admin API OpenAPI specification",
|
|
97
|
+
url: "https://api.example.com/admin/openapi.json",
|
|
98
|
+
description: "Administrative API operations.",
|
|
99
|
+
},
|
|
100
|
+
],
|
|
65
101
|
authDocsUrl: "/docs/authentication",
|
|
66
102
|
scopesDocsUrl: "/docs/scopes",
|
|
67
103
|
rateLimitsUrl: "/docs/rate-limits",
|
|
@@ -98,6 +134,6 @@ export const config = defineConfig({
|
|
|
98
134
|
|
|
99
135
|
## Keep it honest
|
|
100
136
|
|
|
101
|
-
Only list OpenAPI specs, authentication flows, or MCP servers that actually exist. Geistdocs makes product capabilities discoverable, but it does not create APIs or MCP tools for you.
|
|
137
|
+
Only list OpenAPI specs, authentication flows, or MCP servers that actually exist. Geistdocs validates new `openApiSpecs` entries and MCP servers rendered by `/.well-known/mcp.json` as absolute `http` or `https` URLs or root-relative paths. Existing `/agents.md` URL fields keep the same URL handling as previous versions. Geistdocs makes product capabilities discoverable, but it does not create APIs or MCP tools for you.
|
|
102
138
|
|
|
103
|
-
Use `/agents.md` with [llms.txt](/docs/llms-txt), [.md extension](/docs/md), and [Proxy and markdown routes](/docs/proxy) to give agents a complete discovery path.
|
|
139
|
+
Use `/agents.md` and `/.well-known/mcp.json` with [llms.txt](/docs/llms-txt), [.md extension](/docs/md), and [Proxy and markdown routes](/docs/proxy) to give agents a complete discovery path.
|
|
@@ -32,6 +32,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
|
|
|
32
32
|
| `components/geistdocs/docs-layout.tsx` | Customizes the package-backed docs layout, including optional sidebar content. |
|
|
33
33
|
| `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
|
|
34
34
|
| `app/[lang]/agents.md/route.ts` | Configures the agent-readiness entry point. |
|
|
35
|
+
| `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery. |
|
|
35
36
|
| `app/[lang]/llms.txt/route.ts` | Configures the all-docs Markdown endpoint. |
|
|
36
37
|
| `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses. |
|
|
37
38
|
| `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
|
|
@@ -77,7 +77,7 @@ Advanced projects can use package APIs for versioned docs, multiple content sour
|
|
|
77
77
|
- Local content in `content/docs`
|
|
78
78
|
- Search and Ask AI
|
|
79
79
|
- Page actions, including feedback, copy page, open in chat, and edit on GitHub
|
|
80
|
-
- Agent-readiness metadata with `/agents.md`
|
|
80
|
+
- Agent-readiness metadata with `/agents.md` and `/.well-known/mcp.json`
|
|
81
81
|
- Raw Markdown routes for AI tools
|
|
82
82
|
- `llms.txt`
|
|
83
83
|
- Versioned docs and multiple content sources
|
|
@@ -18,7 +18,7 @@ Geistdocs implements the [llms.txt standard](https://llmstxt.org/), a convention
|
|
|
18
18
|
|
|
19
19
|
## What it is
|
|
20
20
|
|
|
21
|
-
The `/llms.txt` endpoint returns all configured documentation pages as Markdown in a single response. Each page is separated by blank lines so AI tools can parse the complete documentation set.
|
|
21
|
+
The `/llms.txt` endpoint returns all configured documentation pages as Markdown in a single response. Each page is separated by blank lines so AI tools can parse the complete documentation set. When agent metadata is configured, page-level Markdown also links agents to `/agents.md` for API and MCP discovery.
|
|
22
22
|
|
|
23
23
|
### Access
|
|
24
24
|
|
|
@@ -26,7 +26,7 @@ Create a working branch and inventory the current site before replacing code:
|
|
|
26
26
|
- Public route families, such as `/docs`, `/api-reference`, `/guides`, or `/`.
|
|
27
27
|
- Existing `middleware.ts` or `proxy.ts` behavior.
|
|
28
28
|
- Static files that overlap package routes, such as `public/llms.txt`.
|
|
29
|
-
- Search, chat, `llms.txt`, page-level Markdown, `sitemap.md`, `agents.md`, RSS, and Open Graph routes.
|
|
29
|
+
- Search, chat, `llms.txt`, page-level Markdown, `sitemap.md`, `agents.md`, `/.well-known/mcp.json`, RSS, and Open Graph routes.
|
|
30
30
|
- Tailwind CSS version and custom plugins.
|
|
31
31
|
- Direct app usage of `ai` or `@ai-sdk/react` outside Geistdocs.
|
|
32
32
|
- Environment variables required by the homepage, docs routes, or API routes.
|
|
@@ -213,6 +213,15 @@ export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
|
|
|
213
213
|
});
|
|
214
214
|
```
|
|
215
215
|
|
|
216
|
+
```ts title="app/[lang]/.well-known/mcp.json/route.ts"
|
|
217
|
+
import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
|
|
218
|
+
import { config } from "@/lib/geistdocs/config";
|
|
219
|
+
|
|
220
|
+
export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
|
|
221
|
+
config,
|
|
222
|
+
});
|
|
223
|
+
```
|
|
224
|
+
|
|
216
225
|
Delete `public/llms.txt` after adding `createLlmsRoute`. Static files in `public` can mask App Router route behavior.
|
|
217
226
|
|
|
218
227
|
## Add search and Ask AI routes
|
|
@@ -354,6 +363,7 @@ Check these URLs locally:
|
|
|
354
363
|
- `/llms.txt`.
|
|
355
364
|
- `/sitemap.md`.
|
|
356
365
|
- `/agents.md`.
|
|
366
|
+
- `/.well-known/mcp.json` if `agent.mcp.servers` is configured.
|
|
357
367
|
- A page-level Markdown URL such as `/docs/getting-started.mdx`.
|
|
358
368
|
- A non-docs route that should not be rewritten as Markdown, such as the homepage.
|
|
359
369
|
|
|
@@ -361,4 +371,4 @@ Check these URLs locally:
|
|
|
361
371
|
|
|
362
372
|
- Read [Configuration](/docs/configuration) to review package config options.
|
|
363
373
|
- Read [Proxy and markdown routes](/docs/proxy) to tune request handling.
|
|
364
|
-
- Read [Agent readiness](/docs/agent-readiness) to configure `/agents.md` for AI agents.
|
|
374
|
+
- Read [Agent readiness](/docs/agent-readiness) to configure `/agents.md` and `/.well-known/mcp.json` for AI agents.
|
package/template/package.json
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"@streamdown/code": "^1.0.1",
|
|
19
19
|
"@vercel/agent-readability": "^0.2.1",
|
|
20
20
|
"@vercel/analytics": "^1.6.1",
|
|
21
|
-
"@vercel/geistdocs": "1.
|
|
21
|
+
"@vercel/geistdocs": "1.4.0",
|
|
22
22
|
"@vercel/speed-insights": "^1.3.1",
|
|
23
23
|
"ai": "^6.0.132",
|
|
24
24
|
"class-variance-authority": "^0.7.1",
|