@vercel/geistdocs 1.13.0 → 1.14.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 +11 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +35 -0
- package/dist/footer.d.ts +1 -1
- package/dist/footer.d.ts.map +1 -1
- package/dist/footer.js +1 -1
- package/dist/internal/chat/shell.d.ts.map +1 -1
- package/dist/internal/chat/shell.js +2 -1
- package/dist/internal/external-arrow.d.ts +11 -0
- package/dist/internal/external-arrow.d.ts.map +1 -0
- package/dist/internal/external-arrow.js +17 -0
- package/dist/internal/footer/rss-button.d.ts +3 -1
- package/dist/internal/footer/rss-button.d.ts.map +1 -1
- package/dist/internal/footer/rss-button.js +2 -1
- package/dist/internal/localized-link.d.ts.map +1 -1
- package/dist/internal/localized-link.js +9 -4
- package/dist/internal/navbar/desktop-menu.d.ts.map +1 -1
- package/dist/internal/navbar/desktop-menu.js +5 -1
- package/dist/internal/navbar/mobile-menu.d.ts +3 -2
- package/dist/internal/navbar/mobile-menu.d.ts.map +1 -1
- package/dist/internal/navbar/mobile-menu.js +60 -9
- package/dist/internal/navbar/navbar-logo.d.ts +3 -1
- package/dist/internal/navbar/navbar-logo.d.ts.map +1 -1
- package/dist/internal/navbar/navbar-logo.js +69 -18
- package/dist/internal/page-actions-client.d.ts +1 -0
- package/dist/internal/page-actions-client.d.ts.map +1 -1
- package/dist/internal/page-actions-client.js +1 -3
- package/dist/internal/search.d.ts.map +1 -1
- package/dist/internal/search.js +2 -1
- package/dist/internal/table-of-contents.js +1 -1
- package/dist/internal/version-paths.d.ts +49 -0
- package/dist/internal/version-paths.d.ts.map +1 -0
- package/dist/internal/version-paths.js +57 -0
- package/dist/navbar.d.ts.map +1 -1
- package/dist/navbar.js +5 -2
- package/dist/pages/docs.d.ts +25 -7
- package/dist/pages/docs.d.ts.map +1 -1
- package/dist/pages/docs.js +40 -8
- package/dist/proxy.d.ts +4 -3
- package/dist/proxy.d.ts.map +1 -1
- package/dist/proxy.js +124 -46
- package/dist/routes/agents.d.ts +1 -1
- package/dist/routes/agents.d.ts.map +1 -1
- package/dist/routes/agents.js +27 -16
- package/dist/routes/chat.d.ts +1 -1
- package/dist/routes/chat.d.ts.map +1 -1
- package/dist/routes/chat.js +18 -11
- package/dist/routes/discovery.d.ts +6 -2
- package/dist/routes/discovery.d.ts.map +1 -1
- package/dist/routes/discovery.js +6 -12
- package/dist/routes/sitemap.d.ts +3 -2
- package/dist/routes/sitemap.d.ts.map +1 -1
- package/dist/routes/sitemap.js +18 -5
- package/dist/source.d.ts +39 -2
- package/dist/source.d.ts.map +1 -1
- package/dist/source.js +111 -13
- package/dist/versions.d.ts +22 -2
- package/dist/versions.d.ts.map +1 -1
- package/dist/versions.js +26 -3
- package/docs/agents.md +1 -1
- package/docs/llms.txt +117 -2
- package/docs/manifest.json +1 -1
- package/docs/pages/configuration.md +23 -1
- package/docs/pages/md.md +4 -0
- package/docs/pages/migration.md +4 -0
- package/docs/pages/proxy.md +15 -0
- package/docs/pages/rss.md +2 -0
- package/docs/pages/versioned-docs.md +68 -0
- package/package.json +1 -1
- package/template/AGENTS.md +2 -0
- package/template/app/[lang]/rss.xml/route.ts +7 -3
- package/template/app/global.css +0 -1
- package/template/content/docs/configuration.mdx +23 -1
- package/template/content/docs/md.mdx +4 -0
- package/template/content/docs/migration.mdx +4 -0
- package/template/content/docs/proxy.mdx +15 -0
- package/template/content/docs/rss.mdx +2 -0
- package/template/content/docs/versioned-docs.mdx +68 -0
- package/template/package.json +1 -1
- package/theme.css +16 -0
package/docs/pages/migration.md
CHANGED
|
@@ -147,6 +147,8 @@ export const geistdocsSource = createSource({
|
|
|
147
147
|
});
|
|
148
148
|
```
|
|
149
149
|
|
|
150
|
+
If the Next.js application also uses `basePath`, pass the same value through `defineConfig` but do not add it to `baseUrl`, `content.route`, `getPageUrl`, or `markdownRoutes`. Those values remain app-local. Geistdocs adds the public prefix to page actions, metadata, generated Markdown, discovery links, chat citations, and proxy destinations.
|
|
151
|
+
|
|
150
152
|
## Add route adapters
|
|
151
153
|
|
|
152
154
|
Keep App Router files thin. Route files should call package helpers instead of copying package internals.
|
|
@@ -321,6 +323,8 @@ const proxy = createProxy({
|
|
|
321
323
|
});
|
|
322
324
|
```
|
|
323
325
|
|
|
326
|
+
For a base-path application whose root page is documentation, add `"/"` to the static proxy matcher and verify `<basePath>/index.md`. Keep normal application and API paths out of a broad root Markdown mapping with matcher exclusions or a `before` hook.
|
|
327
|
+
|
|
324
328
|
## Configure Tailwind CSS
|
|
325
329
|
|
|
326
330
|
Tailwind CSS v4 requires `@source` entries for package components and related dependencies.
|
package/docs/pages/proxy.md
CHANGED
|
@@ -121,6 +121,8 @@ With these mappings:
|
|
|
121
121
|
|
|
122
122
|
Use `[lang]` in the destination when your markdown route is nested under `app/[lang]`. Use `*path` or `:path*` to insert the matched wildcard path.
|
|
123
123
|
|
|
124
|
+
`markdownRoutes` are app-local even when `config.basePath` is set. For a Next.js `basePath` of `/docs`, keep a mapping such as `{ from: "/*path", to: "/[lang]/llms.mdx/*path" }`. `createProxy` preserves `/docs` when it rewrites the public request.
|
|
125
|
+
|
|
124
126
|
## Root-mounted docs
|
|
125
127
|
|
|
126
128
|
For docs served from the site root, set the source `baseUrl` and config route to `/`:
|
|
@@ -162,6 +164,19 @@ const proxy = createProxy({
|
|
|
162
164
|
});
|
|
163
165
|
```
|
|
164
166
|
|
|
167
|
+
When root-mounted docs are the entire base-path application, include `"/"` explicitly in the static matcher. Next.js does not apply a catch-all matcher to the base-path root:
|
|
168
|
+
|
|
169
|
+
```ts title="proxy.ts"
|
|
170
|
+
export const config = {
|
|
171
|
+
matcher: [
|
|
172
|
+
"/",
|
|
173
|
+
"/((?!api(?:/|$)|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
|
|
174
|
+
],
|
|
175
|
+
};
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
The package keeps `llms.txt`, `sitemap.md`, `agents.md`, MCP discovery, and RSS out of root page-Markdown negotiation. Continue to exclude site-specific application and API routes with the matcher or a `before` hook. A root Markdown page is exposed as `/index.md`, or `<basePath>/index.md` publicly.
|
|
179
|
+
|
|
165
180
|
## Hook context
|
|
166
181
|
|
|
167
182
|
Both `before` and `after` receive the same context:
|
package/docs/pages/rss.md
CHANGED
|
@@ -47,6 +47,8 @@ Users can subscribe to this URL using:
|
|
|
47
47
|
|
|
48
48
|
An RSS button appears in the navigation bar so readers can discover and subscribe to your feed. Clicking the button opens the RSS XML in a new tab.
|
|
49
49
|
|
|
50
|
+
The package Footer applies `config.basePath` to this link. Custom RSS generators must also apply the base path to channel and item URLs; source `page.url` values intentionally remain app-local for Next.js navigation.
|
|
51
|
+
|
|
50
52
|
## Feed Format
|
|
51
53
|
|
|
52
54
|
The RSS feed follows the RSS 2.0 specification and includes:
|
|
@@ -220,6 +220,74 @@ For host-based versions, use `href` instead of `routePrefix`:
|
|
|
220
220
|
/>
|
|
221
221
|
```
|
|
222
222
|
|
|
223
|
+
## Avoid 404s when switching versions
|
|
224
|
+
|
|
225
|
+
By default the selector swaps the route prefix without checking that the page
|
|
226
|
+
exists in the target version, so pages that exist in only one version 404 on
|
|
227
|
+
switch. Pass `paths` — computed server-side with `collectVersionSwitchPaths` —
|
|
228
|
+
and the selector falls back to the nearest existing ancestor (or the version's
|
|
229
|
+
docs root) instead:
|
|
230
|
+
|
|
231
|
+
```tsx title="app/[lang]/docs/layout.tsx"
|
|
232
|
+
import { collectVersionSwitchPaths } from "@vercel/geistdocs/source";
|
|
233
|
+
import { GeistdocsVersionSelect } from "@vercel/geistdocs/versions";
|
|
234
|
+
import { config } from "@/lib/geistdocs/config";
|
|
235
|
+
import { versions } from "@/lib/geistdocs/source";
|
|
236
|
+
|
|
237
|
+
const DocsLayout = async ({ children, params }) => {
|
|
238
|
+
const { lang } = await params;
|
|
239
|
+
|
|
240
|
+
return (
|
|
241
|
+
<GeistdocsDocsLayout
|
|
242
|
+
config={config}
|
|
243
|
+
sidebarTop={
|
|
244
|
+
<GeistdocsVersionSelect
|
|
245
|
+
current={versions.currentVersion}
|
|
246
|
+
paths={collectVersionSwitchPaths({ lang, versions })}
|
|
247
|
+
versions={config.versions}
|
|
248
|
+
/>
|
|
249
|
+
}
|
|
250
|
+
tree={versions.current.source.pageTree[lang]}
|
|
251
|
+
>
|
|
252
|
+
{children}
|
|
253
|
+
</GeistdocsDocsLayout>
|
|
254
|
+
);
|
|
255
|
+
};
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
`collectVersionSwitchPaths` enumerates every page of every version from the
|
|
259
|
+
`createVersionedSources` output and returns paths relative to each version's
|
|
260
|
+
`routePrefix`, plus each version's docs root as the fallback landing page.
|
|
261
|
+
|
|
262
|
+
When an app rewrites loader URLs at render time (for example serving a
|
|
263
|
+
`baseUrl: "/docs"` source under `/v5` with a custom `getPageUrl`), pass the
|
|
264
|
+
same mapping so the collected paths match the public URLs. For sources that
|
|
265
|
+
span several loaders per version (for example separate docs and cookbook
|
|
266
|
+
sources), use the lower-level `collectVersionPaths` per version instead:
|
|
267
|
+
|
|
268
|
+
```tsx
|
|
269
|
+
import { collectVersionPaths } from "@vercel/geistdocs/source";
|
|
270
|
+
|
|
271
|
+
const paths = {
|
|
272
|
+
v4: {
|
|
273
|
+
fallbackPath: "/docs",
|
|
274
|
+
paths: collectVersionPaths({ lang, sources: [v4Docs, v4Cookbook] }),
|
|
275
|
+
},
|
|
276
|
+
v5: {
|
|
277
|
+
fallbackPath: "/docs",
|
|
278
|
+
paths: collectVersionPaths({
|
|
279
|
+
lang,
|
|
280
|
+
routePrefix: "/v5",
|
|
281
|
+
sources: [v5Docs, v5Cookbook],
|
|
282
|
+
}),
|
|
283
|
+
},
|
|
284
|
+
};
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
Fallback resolution only applies to `routePrefix` versions. Host-based
|
|
288
|
+
versions (`href`) always keep the plain path swap, since the target host's
|
|
289
|
+
pages can't be enumerated locally.
|
|
290
|
+
|
|
223
291
|
## Configure markdown routes
|
|
224
292
|
|
|
225
293
|
Each public route family needs a matching markdown route in `proxy.ts`. Read [Proxy and markdown routes](/docs/proxy) for the proxy configuration.
|
package/package.json
CHANGED
package/template/AGENTS.md
CHANGED
|
@@ -56,6 +56,8 @@ Use these instructions when an AI coding agent edits this project.
|
|
|
56
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.
|
|
57
57
|
- When adding custom proxy behavior, prefer `before`, `after`, and `markdownRoutes` options on `createProxy` instead of replacing the proxy.
|
|
58
58
|
- Use explicit `markdownRoutes` for root-mounted docs or any site where homepage/app routes coexist with docs routes.
|
|
59
|
+
- Keep source URLs, navigation links, `getPageUrl`, and `markdownRoutes` app-local when `config.basePath` is set. Geistdocs derives public page-action and Markdown URLs separately.
|
|
60
|
+
- Include `"/"` explicitly in the static proxy matcher when a Next.js base-path application serves documentation at its app root.
|
|
59
61
|
|
|
60
62
|
## Ask AI and Vertex proxy guidelines
|
|
61
63
|
|
|
@@ -1,10 +1,14 @@
|
|
|
1
|
+
import { getPublicPath } from "@vercel/geistdocs/config";
|
|
1
2
|
import { Feed } from "feed";
|
|
2
3
|
import type { NextRequest } from "next/server";
|
|
3
4
|
import { title } from "@/geistdocs";
|
|
5
|
+
import { config } from "@/lib/geistdocs/config";
|
|
4
6
|
import { source } from "@/lib/geistdocs/source";
|
|
5
7
|
|
|
6
8
|
const protocol = process.env.NODE_ENV === "production" ? "https" : "http";
|
|
7
9
|
const baseUrl = `${protocol}://${process.env.NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL}`;
|
|
10
|
+
const sitePath = getPublicPath("/", config.basePath);
|
|
11
|
+
const siteUrl = sitePath === "/" ? baseUrl : `${baseUrl}${sitePath}`;
|
|
8
12
|
|
|
9
13
|
export const revalidate = false;
|
|
10
14
|
|
|
@@ -15,8 +19,8 @@ export const GET = async (
|
|
|
15
19
|
const { lang } = await params;
|
|
16
20
|
const feed = new Feed({
|
|
17
21
|
title,
|
|
18
|
-
id:
|
|
19
|
-
link:
|
|
22
|
+
id: siteUrl,
|
|
23
|
+
link: siteUrl,
|
|
20
24
|
language: lang,
|
|
21
25
|
copyright: `All rights reserved ${new Date().getFullYear()}, Vercel`,
|
|
22
26
|
});
|
|
@@ -32,7 +36,7 @@ export const GET = async (
|
|
|
32
36
|
id: page.url,
|
|
33
37
|
title: data.title ?? page.url,
|
|
34
38
|
description: data.description,
|
|
35
|
-
link: `${baseUrl}${page.url}`,
|
|
39
|
+
link: `${baseUrl}${getPublicPath(page.url, config.basePath)}`,
|
|
36
40
|
date: new Date(data.lastModified ?? new Date()),
|
|
37
41
|
author: [
|
|
38
42
|
{
|
package/template/app/global.css
CHANGED
|
@@ -177,6 +177,24 @@ export default defineGeistdocsSourceConfig();
|
|
|
177
177
|
|
|
178
178
|
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.
|
|
179
179
|
|
|
180
|
+
## Next.js base paths
|
|
181
|
+
|
|
182
|
+
When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
|
|
183
|
+
|
|
184
|
+
```ts title="next.config.ts"
|
|
185
|
+
const config: NextConfig = {
|
|
186
|
+
basePath: "/docs",
|
|
187
|
+
};
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
```tsx title="geistdocs.tsx"
|
|
191
|
+
export const basePath = "/docs";
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Keep `content.route`, source `baseUrl`, navigation links, `getPageUrl`, search results, and proxy `markdownRoutes` app-local. Next.js applies the mount prefix to navigation. Geistdocs applies `basePath` separately to public page actions, Markdown metadata, generated Markdown and sitemap links, Ask AI citations, RSS discovery, and proxy rewrites.
|
|
195
|
+
|
|
196
|
+
For example, a root-mounted source with `baseUrl: "/"` still uses `page.url === "/guide"`. The public page is `/docs/guide`, and its Markdown URL is `/docs/guide.md`. The root page uses `/docs/index.md`.
|
|
197
|
+
|
|
180
198
|
## Page actions
|
|
181
199
|
|
|
182
200
|
Content actions appear in the **Copy page** menu beside the page title. **Scroll to top** and **Give feedback** remain below the table of contents so they stay available while you read. These actions are enabled by default and can be disabled through `defineConfig` in `lib/geistdocs/config.tsx`:
|
|
@@ -270,7 +288,11 @@ const docsPage = createDocsPage({
|
|
|
270
288
|
});
|
|
271
289
|
```
|
|
272
290
|
|
|
273
|
-
Use `getPageUrl` when the
|
|
291
|
+
Use `getPageUrl` when the app-local route differs from the source URL, such as `/v5/docs`. Geistdocs keeps that value app-local for previous and next navigation, then derives the public action URL with `config.basePath`.
|
|
292
|
+
|
|
293
|
+
For unusual deployments, `getPublicPageUrl` can override the public HTML URL and `getMarkdownUrl` can override the Copy Page, View as Markdown, and metadata URL. Most sites should use the package defaults so these surfaces cannot drift apart.
|
|
294
|
+
|
|
295
|
+
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. The `tableOfContent.header` and `tableOfContent.footer` slots render immediately above and below the table of contents.
|
|
274
296
|
|
|
275
297
|
## Package-owned runtime
|
|
276
298
|
|
|
@@ -35,6 +35,10 @@ The `.mdx` version returns:
|
|
|
35
35
|
- The full processed Markdown content
|
|
36
36
|
- No HTML, styling, or navigation
|
|
37
37
|
|
|
38
|
+
For a docs section mounted at `/docs`, the section root remains `/docs.md`. For a source mounted at the app root with `baseUrl: "/"`, Geistdocs uses `/index.md` for the root page. If Next.js has `basePath: "/docs"`, that public root Markdown URL is `/docs/index.md`.
|
|
39
|
+
|
|
40
|
+
Copy Page, View as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
|
|
41
|
+
|
|
38
42
|
## Use cases
|
|
39
43
|
|
|
40
44
|
This feature is particularly useful for:
|
|
@@ -145,6 +145,8 @@ export const geistdocsSource = createSource({
|
|
|
145
145
|
});
|
|
146
146
|
```
|
|
147
147
|
|
|
148
|
+
If the Next.js application also uses `basePath`, pass the same value through `defineConfig` but do not add it to `baseUrl`, `content.route`, `getPageUrl`, or `markdownRoutes`. Those values remain app-local. Geistdocs adds the public prefix to page actions, metadata, generated Markdown, discovery links, chat citations, and proxy destinations.
|
|
149
|
+
|
|
148
150
|
## Add route adapters
|
|
149
151
|
|
|
150
152
|
Keep App Router files thin. Route files should call package helpers instead of copying package internals.
|
|
@@ -319,6 +321,8 @@ const proxy = createProxy({
|
|
|
319
321
|
});
|
|
320
322
|
```
|
|
321
323
|
|
|
324
|
+
For a base-path application whose root page is documentation, add `"/"` to the static proxy matcher and verify `<basePath>/index.md`. Keep normal application and API paths out of a broad root Markdown mapping with matcher exclusions or a `before` hook.
|
|
325
|
+
|
|
322
326
|
## Configure Tailwind CSS
|
|
323
327
|
|
|
324
328
|
Tailwind CSS v4 requires `@source` entries for package components and related dependencies.
|
|
@@ -119,6 +119,8 @@ With these mappings:
|
|
|
119
119
|
|
|
120
120
|
Use `[lang]` in the destination when your markdown route is nested under `app/[lang]`. Use `*path` or `:path*` to insert the matched wildcard path.
|
|
121
121
|
|
|
122
|
+
`markdownRoutes` are app-local even when `config.basePath` is set. For a Next.js `basePath` of `/docs`, keep a mapping such as `{ from: "/*path", to: "/[lang]/llms.mdx/*path" }`. `createProxy` preserves `/docs` when it rewrites the public request.
|
|
123
|
+
|
|
122
124
|
## Root-mounted docs
|
|
123
125
|
|
|
124
126
|
For docs served from the site root, set the source `baseUrl` and config route to `/`:
|
|
@@ -160,6 +162,19 @@ const proxy = createProxy({
|
|
|
160
162
|
});
|
|
161
163
|
```
|
|
162
164
|
|
|
165
|
+
When root-mounted docs are the entire base-path application, include `"/"` explicitly in the static matcher. Next.js does not apply a catch-all matcher to the base-path root:
|
|
166
|
+
|
|
167
|
+
```ts title="proxy.ts"
|
|
168
|
+
export const config = {
|
|
169
|
+
matcher: [
|
|
170
|
+
"/",
|
|
171
|
+
"/((?!api(?:/|$)|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
|
|
172
|
+
],
|
|
173
|
+
};
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
The package keeps `llms.txt`, `sitemap.md`, `agents.md`, MCP discovery, and RSS out of root page-Markdown negotiation. Continue to exclude site-specific application and API routes with the matcher or a `before` hook. A root Markdown page is exposed as `/index.md`, or `<basePath>/index.md` publicly.
|
|
177
|
+
|
|
163
178
|
## Hook context
|
|
164
179
|
|
|
165
180
|
Both `before` and `after` receive the same context:
|
|
@@ -45,6 +45,8 @@ Users can subscribe to this URL using:
|
|
|
45
45
|
|
|
46
46
|
An RSS button appears in the navigation bar so readers can discover and subscribe to your feed. Clicking the button opens the RSS XML in a new tab.
|
|
47
47
|
|
|
48
|
+
The package Footer applies `config.basePath` to this link. Custom RSS generators must also apply the base path to channel and item URLs; source `page.url` values intentionally remain app-local for Next.js navigation.
|
|
49
|
+
|
|
48
50
|
## Feed Format
|
|
49
51
|
|
|
50
52
|
The RSS feed follows the RSS 2.0 specification and includes:
|
|
@@ -218,6 +218,74 @@ For host-based versions, use `href` instead of `routePrefix`:
|
|
|
218
218
|
/>
|
|
219
219
|
```
|
|
220
220
|
|
|
221
|
+
## Avoid 404s when switching versions
|
|
222
|
+
|
|
223
|
+
By default the selector swaps the route prefix without checking that the page
|
|
224
|
+
exists in the target version, so pages that exist in only one version 404 on
|
|
225
|
+
switch. Pass `paths` — computed server-side with `collectVersionSwitchPaths` —
|
|
226
|
+
and the selector falls back to the nearest existing ancestor (or the version's
|
|
227
|
+
docs root) instead:
|
|
228
|
+
|
|
229
|
+
```tsx title="app/[lang]/docs/layout.tsx"
|
|
230
|
+
import { collectVersionSwitchPaths } from "@vercel/geistdocs/source";
|
|
231
|
+
import { GeistdocsVersionSelect } from "@vercel/geistdocs/versions";
|
|
232
|
+
import { config } from "@/lib/geistdocs/config";
|
|
233
|
+
import { versions } from "@/lib/geistdocs/source";
|
|
234
|
+
|
|
235
|
+
const DocsLayout = async ({ children, params }) => {
|
|
236
|
+
const { lang } = await params;
|
|
237
|
+
|
|
238
|
+
return (
|
|
239
|
+
<GeistdocsDocsLayout
|
|
240
|
+
config={config}
|
|
241
|
+
sidebarTop={
|
|
242
|
+
<GeistdocsVersionSelect
|
|
243
|
+
current={versions.currentVersion}
|
|
244
|
+
paths={collectVersionSwitchPaths({ lang, versions })}
|
|
245
|
+
versions={config.versions}
|
|
246
|
+
/>
|
|
247
|
+
}
|
|
248
|
+
tree={versions.current.source.pageTree[lang]}
|
|
249
|
+
>
|
|
250
|
+
{children}
|
|
251
|
+
</GeistdocsDocsLayout>
|
|
252
|
+
);
|
|
253
|
+
};
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
`collectVersionSwitchPaths` enumerates every page of every version from the
|
|
257
|
+
`createVersionedSources` output and returns paths relative to each version's
|
|
258
|
+
`routePrefix`, plus each version's docs root as the fallback landing page.
|
|
259
|
+
|
|
260
|
+
When an app rewrites loader URLs at render time (for example serving a
|
|
261
|
+
`baseUrl: "/docs"` source under `/v5` with a custom `getPageUrl`), pass the
|
|
262
|
+
same mapping so the collected paths match the public URLs. For sources that
|
|
263
|
+
span several loaders per version (for example separate docs and cookbook
|
|
264
|
+
sources), use the lower-level `collectVersionPaths` per version instead:
|
|
265
|
+
|
|
266
|
+
```tsx
|
|
267
|
+
import { collectVersionPaths } from "@vercel/geistdocs/source";
|
|
268
|
+
|
|
269
|
+
const paths = {
|
|
270
|
+
v4: {
|
|
271
|
+
fallbackPath: "/docs",
|
|
272
|
+
paths: collectVersionPaths({ lang, sources: [v4Docs, v4Cookbook] }),
|
|
273
|
+
},
|
|
274
|
+
v5: {
|
|
275
|
+
fallbackPath: "/docs",
|
|
276
|
+
paths: collectVersionPaths({
|
|
277
|
+
lang,
|
|
278
|
+
routePrefix: "/v5",
|
|
279
|
+
sources: [v5Docs, v5Cookbook],
|
|
280
|
+
}),
|
|
281
|
+
},
|
|
282
|
+
};
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Fallback resolution only applies to `routePrefix` versions. Host-based
|
|
286
|
+
versions (`href`) always keep the plain path swap, since the target host's
|
|
287
|
+
pages can't be enumerated locally.
|
|
288
|
+
|
|
221
289
|
## Configure markdown routes
|
|
222
290
|
|
|
223
291
|
Each public route family needs a matching markdown route in `proxy.ts`. Read [Proxy and markdown routes](/docs/proxy) for the proxy configuration.
|
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.14.1",
|
|
22
22
|
"@vercel/speed-insights": "^1.3.1",
|
|
23
23
|
"ai": "^6.0.132",
|
|
24
24
|
"class-variance-authority": "^0.7.1",
|
package/theme.css
CHANGED
|
@@ -876,6 +876,10 @@
|
|
|
876
876
|
padding-left: max(1rem, env(safe-area-inset-left));
|
|
877
877
|
}
|
|
878
878
|
|
|
879
|
+
.geistdocs-toc-scroll > div[style*="mask-image"] {
|
|
880
|
+
inset-inline-start: -0.5px;
|
|
881
|
+
}
|
|
882
|
+
|
|
879
883
|
[data-mobile-docs-bar] {
|
|
880
884
|
padding-right: max(1.5rem, env(safe-area-inset-right));
|
|
881
885
|
padding-left: max(1.5rem, env(safe-area-inset-left));
|
|
@@ -906,3 +910,15 @@ body:has([data-home-route]) header {
|
|
|
906
910
|
html[data-scrolled] body:has([data-home-route]) header {
|
|
907
911
|
border-bottom-color: var(--ds-gray-alpha-400) !important;
|
|
908
912
|
}
|
|
913
|
+
/* Hide the header border while the dropdown or mobile menu is open. `html body`
|
|
914
|
+
matches the scroll-reveal rule's specificity so this (later) rule wins there,
|
|
915
|
+
and covers every other route too. */
|
|
916
|
+
html body
|
|
917
|
+
header:has(
|
|
918
|
+
[data-slot="navigation-menu-trigger"][data-state="open"],
|
|
919
|
+
[data-slot="mobile-menu-toggle"][aria-expanded="true"]
|
|
920
|
+
) {
|
|
921
|
+
border-bottom-color: transparent !important;
|
|
922
|
+
/* Hide instantly; the scroll-reveal fade above still applies when closed. */
|
|
923
|
+
transition: none !important;
|
|
924
|
+
}
|