@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/dist/routes/sitemap.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { getPublicPath } from "../config";
|
|
1
2
|
import { isPageVisibleForSurface, } from "../internal/page-visibility";
|
|
2
3
|
import { isGeistdocsSourceBundle } from "../source";
|
|
3
4
|
const DOCS_PREFIX_PATTERN = /^\/docs\/?/;
|
|
@@ -18,6 +19,7 @@ function buildTree(pages) {
|
|
|
18
19
|
url: page.url,
|
|
19
20
|
type: page.data.type,
|
|
20
21
|
summary: page.data.summary,
|
|
22
|
+
sourceUrl: page.sourceUrl ?? page.url,
|
|
21
23
|
prerequisites: page.data.prerequisites,
|
|
22
24
|
product: page.data.product,
|
|
23
25
|
lastmod: page.data.lastModified
|
|
@@ -102,7 +104,7 @@ function renderNode(node, indent, parentTitle) {
|
|
|
102
104
|
if (prereqs) {
|
|
103
105
|
segments.push(`Prerequisites: ${prereqs}`);
|
|
104
106
|
}
|
|
105
|
-
const topics = extractTopics(node.
|
|
107
|
+
const topics = extractTopics(node.sourceUrl, node.product);
|
|
106
108
|
if (topics.length > 0) {
|
|
107
109
|
segments.push(`Topics: ${topics.join(", ")}`);
|
|
108
110
|
}
|
|
@@ -120,9 +122,20 @@ const resolveSitemapSections = (source, sources) => {
|
|
|
120
122
|
}
|
|
121
123
|
return sections;
|
|
122
124
|
};
|
|
123
|
-
const getSectionPages = (source, lang) =>
|
|
124
|
-
|
|
125
|
-
|
|
125
|
+
const getSectionPages = (source, lang, basePath) => {
|
|
126
|
+
const pages = (isGeistdocsSourceBundle(source)
|
|
127
|
+
? source.source.getPages(lang)
|
|
128
|
+
: source.getPages(lang));
|
|
129
|
+
return pages.map((page) => ({
|
|
130
|
+
...page,
|
|
131
|
+
data: {
|
|
132
|
+
...page.data,
|
|
133
|
+
prerequisites: page.data.prerequisites?.map((prerequisite) => getPublicPath(prerequisite, basePath)),
|
|
134
|
+
},
|
|
135
|
+
sourceUrl: page.url,
|
|
136
|
+
url: getPublicPath(page.url, basePath),
|
|
137
|
+
}));
|
|
138
|
+
};
|
|
126
139
|
const getSectionTitle = (section) => section.title ??
|
|
127
140
|
(isGeistdocsSourceBundle(section.source) ? section.source.label : undefined);
|
|
128
141
|
export const createSitemapMarkdownRoute = ({ config, source, sources, title = "Documentation Sitemap", transform, }) => {
|
|
@@ -148,7 +161,7 @@ It is not intended to replace individual docs.
|
|
|
148
161
|
`;
|
|
149
162
|
const body = sections
|
|
150
163
|
.map((section) => {
|
|
151
|
-
const pages = getSectionPages(section.source, lang).filter((page) => isPageVisibleForSurface(page, "sitemap"));
|
|
164
|
+
const pages = getSectionPages(section.source, lang, config.basePath).filter((page) => isPageVisibleForSurface(page, "sitemap"));
|
|
152
165
|
const tree = buildTree(pages);
|
|
153
166
|
const renderedTree = tree
|
|
154
167
|
.map((node) => renderNode(node, 0))
|
package/dist/source.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { type InferPageType, loader } from "fumadocs-core/source";
|
|
2
|
-
import type
|
|
2
|
+
import { type GeistdocsConfig, type GeistdocsPageSurface } from "./config.js";
|
|
3
|
+
import { type GeistdocsVersionPaths } from "./internal/version-paths.js";
|
|
4
|
+
export type { GeistdocsVersionPaths } from "./internal/version-paths.js";
|
|
3
5
|
type LoaderOptions = Parameters<typeof loader>[0];
|
|
4
6
|
export interface FumadocsCollection {
|
|
5
7
|
toFumadocsSource(): LoaderOptions["source"];
|
|
@@ -178,5 +180,40 @@ export declare const createVersionedSources: ({ config, current, versions, }: Cr
|
|
|
178
180
|
};
|
|
179
181
|
currentVersion: string;
|
|
180
182
|
};
|
|
181
|
-
export {
|
|
183
|
+
export interface CollectVersionPathsOptions {
|
|
184
|
+
/**
|
|
185
|
+
* Map a page to its public URL when the app rewrites loader URLs at render
|
|
186
|
+
* time (e.g. `({ page }) => \`/v5${page.url}\``). Defaults to `page.url`.
|
|
187
|
+
*/
|
|
188
|
+
getPageUrl?: (context: {
|
|
189
|
+
page: {
|
|
190
|
+
slugs: string[];
|
|
191
|
+
url: string;
|
|
192
|
+
};
|
|
193
|
+
}) => string;
|
|
194
|
+
lang?: string;
|
|
195
|
+
/** The version's public route prefix, stripped from every collected path. */
|
|
196
|
+
routePrefix?: string;
|
|
197
|
+
sources: GeistdocsSourceBundle | GeistdocsSourceBundle[];
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* Collect the prefix-relative paths of every page in one version's sources.
|
|
201
|
+
* Pass the result to the version switcher (via `GeistdocsVersionSelect`'s
|
|
202
|
+
* `paths` prop) so switching never lands on a page that doesn't exist in the
|
|
203
|
+
* target version. Handles both URL shapes: loaders whose `baseUrl` already
|
|
204
|
+
* includes the version prefix, and loaders whose URLs get prefixed at render
|
|
205
|
+
* time (via `routePrefix` / `getPageUrl`).
|
|
206
|
+
*/
|
|
207
|
+
export declare const collectVersionPaths: ({ getPageUrl, lang, routePrefix, sources, }: CollectVersionPathsOptions) => string[];
|
|
208
|
+
export interface CollectVersionSwitchPathsOptions {
|
|
209
|
+
getPageUrl?: CollectVersionPathsOptions["getPageUrl"];
|
|
210
|
+
lang?: string;
|
|
211
|
+
versions: Pick<ReturnType<typeof createVersionedSources>, "all">;
|
|
212
|
+
}
|
|
213
|
+
/**
|
|
214
|
+
* Build the `paths` prop for `GeistdocsVersionSelect` from
|
|
215
|
+
* `createVersionedSources` output: for each version, the prefix-relative
|
|
216
|
+
* paths of its pages plus its docs root as the fallback landing page.
|
|
217
|
+
*/
|
|
218
|
+
export declare const collectVersionSwitchPaths: ({ getPageUrl, lang, versions, }: CollectVersionSwitchPathsOptions) => Record<string, GeistdocsVersionPaths>;
|
|
182
219
|
//# sourceMappingURL=source.d.ts.map
|
package/dist/source.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,MAAM,EAEP,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"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"}
|
package/dist/source.js
CHANGED
|
@@ -1,6 +1,62 @@
|
|
|
1
1
|
import { defineI18n } from "fumadocs-core/i18n";
|
|
2
2
|
import { loader, } from "fumadocs-core/source";
|
|
3
3
|
import { lucideIconsPlugin } from "fumadocs-core/source/lucide-icons";
|
|
4
|
+
import { getPublicPath, withBasePath, } from "./config.js";
|
|
5
|
+
import { stripVersionRoutePrefix, } from "./internal/version-paths.js";
|
|
6
|
+
const MARKDOWN_LINK_PATTERN = /(\]\()(\/(?!\/)[^)\s]*)/g;
|
|
7
|
+
const ROOT_ATTRIBUTE_PATTERN = /(\b(?:href|src)=["'])(\/(?!\/)[^"']*)/g;
|
|
8
|
+
const FENCE_PATTERN = /^\s*(`{3,}|~{3,})/;
|
|
9
|
+
const CLOSING_FENCE_PATTERN = /^\s*(`{3,}|~{3,})\s*$/;
|
|
10
|
+
const FRONTMATTER_FIELD_PATTERN = /^([a-zA-Z][\w-]*):/;
|
|
11
|
+
const FRONTMATTER_CANONICAL_PATTERN = /^(canonical:\s+)(\/(?!\/)\S+)$/;
|
|
12
|
+
const FRONTMATTER_LIST_URL_PATTERN = /^(\s+-\s+)(\/(?!\/)\S+)$/;
|
|
13
|
+
const prefixLineUrl = (line, pattern, basePath) => line.replace(pattern, (_match, prefix, href) => `${prefix}${withBasePath(href, basePath)}`);
|
|
14
|
+
const prefixFrontmatterLinks = (lines, basePath) => {
|
|
15
|
+
let field;
|
|
16
|
+
return lines.map((line) => {
|
|
17
|
+
field = line.match(FRONTMATTER_FIELD_PATTERN)?.[1] ?? field;
|
|
18
|
+
if (field === "canonical") {
|
|
19
|
+
return prefixLineUrl(line, FRONTMATTER_CANONICAL_PATTERN, basePath);
|
|
20
|
+
}
|
|
21
|
+
if (field === "prerequisites" || field === "related") {
|
|
22
|
+
return prefixLineUrl(line, FRONTMATTER_LIST_URL_PATTERN, basePath);
|
|
23
|
+
}
|
|
24
|
+
return line;
|
|
25
|
+
});
|
|
26
|
+
};
|
|
27
|
+
const prefixContentLinks = (lines, basePath) => {
|
|
28
|
+
let fenceMarker;
|
|
29
|
+
return lines.map((line) => {
|
|
30
|
+
if (fenceMarker) {
|
|
31
|
+
const closingFence = line.match(CLOSING_FENCE_PATTERN)?.[1];
|
|
32
|
+
if (closingFence?.[0] === fenceMarker[0] &&
|
|
33
|
+
closingFence.length >= fenceMarker.length) {
|
|
34
|
+
fenceMarker = undefined;
|
|
35
|
+
}
|
|
36
|
+
return line;
|
|
37
|
+
}
|
|
38
|
+
const openingFence = line.match(FENCE_PATTERN)?.[1];
|
|
39
|
+
if (openingFence) {
|
|
40
|
+
fenceMarker = openingFence;
|
|
41
|
+
return line;
|
|
42
|
+
}
|
|
43
|
+
return prefixLineUrl(prefixLineUrl(line, MARKDOWN_LINK_PATTERN, basePath), ROOT_ATTRIBUTE_PATTERN, basePath);
|
|
44
|
+
});
|
|
45
|
+
};
|
|
46
|
+
const prefixMarkdownLinks = (markdown, basePath) => {
|
|
47
|
+
if (!basePath) {
|
|
48
|
+
return markdown;
|
|
49
|
+
}
|
|
50
|
+
const lines = markdown.split("\n");
|
|
51
|
+
const frontmatterEnd = lines[0] === "---" ? lines.indexOf("---", 1) : -1;
|
|
52
|
+
if (frontmatterEnd === -1) {
|
|
53
|
+
return prefixContentLinks(lines, basePath).join("\n");
|
|
54
|
+
}
|
|
55
|
+
return [
|
|
56
|
+
...prefixFrontmatterLinks(lines.slice(0, frontmatterEnd + 1), basePath),
|
|
57
|
+
...prefixContentLinks(lines.slice(frontmatterEnd + 1), basePath),
|
|
58
|
+
].join("\n");
|
|
59
|
+
};
|
|
4
60
|
const getLanguages = (config) => {
|
|
5
61
|
const defaultLanguage = config.defaultLanguage ?? "en";
|
|
6
62
|
const languages = Object.keys(config.translations ?? {});
|
|
@@ -44,9 +100,7 @@ export const createSource = ({ docs, config, baseUrl = "/docs", id, label, markd
|
|
|
44
100
|
const segments = [...page.slugs, "image.png"];
|
|
45
101
|
return {
|
|
46
102
|
segments,
|
|
47
|
-
url: config.basePath
|
|
48
|
-
? `${config.basePath}/og/${segments.join("/")}`
|
|
49
|
-
: `/og/${segments.join("/")}`,
|
|
103
|
+
url: getPublicPath(`/og/${segments.join("/")}`, config.basePath),
|
|
50
104
|
};
|
|
51
105
|
};
|
|
52
106
|
const getPageMarkdown = async (page) => {
|
|
@@ -74,13 +128,21 @@ export const createSource = ({ docs, config, baseUrl = "/docs", id, label, markd
|
|
|
74
128
|
.map((prerequisite) => ` - ${prerequisite}`)
|
|
75
129
|
.join("\n")}`,
|
|
76
130
|
related?.length &&
|
|
77
|
-
`related:\n${related
|
|
131
|
+
`related:\n${related
|
|
132
|
+
.map((entry) => ` - ${entry}`)
|
|
133
|
+
.join("\n")}`,
|
|
78
134
|
"---",
|
|
79
135
|
]
|
|
80
136
|
.filter(Boolean)
|
|
81
137
|
.join("\n");
|
|
138
|
+
const sitemapPath = "/sitemap.md";
|
|
139
|
+
const llmsPath = "/llms.txt";
|
|
140
|
+
const agentsPath = "/agents.md";
|
|
141
|
+
const sitemapLabel = getPublicPath(sitemapPath, config.basePath);
|
|
142
|
+
const llmsLabel = getPublicPath(llmsPath, config.basePath);
|
|
143
|
+
const agentsLabel = getPublicPath(agentsPath, config.basePath);
|
|
82
144
|
const agentDiscoveryLink = config.agent && config.agent.enabled !== false
|
|
83
|
-
?
|
|
145
|
+
? `\n\nFor agent-facing discovery, including API and MCP surfaces, see [${agentsLabel}](${agentsPath})`
|
|
84
146
|
: "";
|
|
85
147
|
const rendered = `${frontmatter}
|
|
86
148
|
|
|
@@ -90,15 +152,15 @@ ${processed}
|
|
|
90
152
|
|
|
91
153
|
---
|
|
92
154
|
|
|
93
|
-
For a semantic overview of all documentation, see [
|
|
155
|
+
For a semantic overview of all documentation, see [${sitemapLabel}](${sitemapPath})
|
|
94
156
|
|
|
95
|
-
For an index of all available documentation, see [
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
157
|
+
For an index of all available documentation, see [${llmsLabel}](${llmsPath})${agentDiscoveryLink}`;
|
|
158
|
+
const transformed = markdown?.transform
|
|
159
|
+
? await markdown.transform(rendered, {
|
|
160
|
+
page: page,
|
|
161
|
+
})
|
|
162
|
+
: rendered;
|
|
163
|
+
return prefixMarkdownLinks(transformed, config.basePath);
|
|
102
164
|
};
|
|
103
165
|
return {
|
|
104
166
|
baseUrl,
|
|
@@ -162,3 +224,39 @@ export const createVersionedSources = ({ config, current, versions, }) => {
|
|
|
162
224
|
currentVersion: current,
|
|
163
225
|
};
|
|
164
226
|
};
|
|
227
|
+
/**
|
|
228
|
+
* Collect the prefix-relative paths of every page in one version's sources.
|
|
229
|
+
* Pass the result to the version switcher (via `GeistdocsVersionSelect`'s
|
|
230
|
+
* `paths` prop) so switching never lands on a page that doesn't exist in the
|
|
231
|
+
* target version. Handles both URL shapes: loaders whose `baseUrl` already
|
|
232
|
+
* includes the version prefix, and loaders whose URLs get prefixed at render
|
|
233
|
+
* time (via `routePrefix` / `getPageUrl`).
|
|
234
|
+
*/
|
|
235
|
+
export const collectVersionPaths = ({ getPageUrl, lang, routePrefix, sources, }) => {
|
|
236
|
+
const bundles = Array.isArray(sources) ? sources : [sources];
|
|
237
|
+
const paths = new Set();
|
|
238
|
+
for (const bundle of bundles) {
|
|
239
|
+
for (const page of bundle.source.getPages(lang)) {
|
|
240
|
+
const url = getPageUrl ? getPageUrl({ page }) : page.url;
|
|
241
|
+
paths.add(stripVersionRoutePrefix(url, routePrefix));
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
return [...paths].sort();
|
|
245
|
+
};
|
|
246
|
+
/**
|
|
247
|
+
* Build the `paths` prop for `GeistdocsVersionSelect` from
|
|
248
|
+
* `createVersionedSources` output: for each version, the prefix-relative
|
|
249
|
+
* paths of its pages plus its docs root as the fallback landing page.
|
|
250
|
+
*/
|
|
251
|
+
export const collectVersionSwitchPaths = ({ getPageUrl, lang, versions, }) => Object.fromEntries(versions.all.map((entry) => [
|
|
252
|
+
entry.id,
|
|
253
|
+
{
|
|
254
|
+
fallbackPath: stripVersionRoutePrefix(entry.source.baseUrl, entry.routePrefix),
|
|
255
|
+
paths: collectVersionPaths({
|
|
256
|
+
getPageUrl,
|
|
257
|
+
lang,
|
|
258
|
+
routePrefix: entry.routePrefix,
|
|
259
|
+
sources: entry.source,
|
|
260
|
+
}),
|
|
261
|
+
},
|
|
262
|
+
]));
|
package/dist/versions.d.ts
CHANGED
|
@@ -1,11 +1,24 @@
|
|
|
1
1
|
import type { ReactNode } from "react";
|
|
2
2
|
import type { GeistdocsVersionConfig, GeistdocsVersionsConfig } from "./config";
|
|
3
|
+
import { type GeistdocsVersionPaths } from "./internal/version-paths.js";
|
|
4
|
+
export type { GeistdocsVersionPaths } from "./internal/version-paths.js";
|
|
3
5
|
export interface GeistdocsRouteSelectItem {
|
|
4
6
|
description?: string;
|
|
7
|
+
/**
|
|
8
|
+
* Landing path (relative to `routePrefix`) when neither the switched path
|
|
9
|
+
* nor any of its ancestors exist in `paths`.
|
|
10
|
+
*/
|
|
11
|
+
fallbackPath?: string;
|
|
5
12
|
href?: string;
|
|
6
13
|
icon?: ReactNode;
|
|
7
14
|
id: string;
|
|
8
15
|
label: string;
|
|
16
|
+
/**
|
|
17
|
+
* Paths (relative to `routePrefix`) that exist for this item. When
|
|
18
|
+
* provided, switching falls back to the nearest existing ancestor instead
|
|
19
|
+
* of landing on a page that doesn't exist in the target version.
|
|
20
|
+
*/
|
|
21
|
+
paths?: readonly string[];
|
|
9
22
|
routePrefix?: string;
|
|
10
23
|
}
|
|
11
24
|
interface ResolveRouteHrefOptions<Item extends GeistdocsRouteSelectItem> {
|
|
@@ -35,11 +48,18 @@ interface GeistdocsRouteSelectProps<Item extends GeistdocsRouteSelectItem> {
|
|
|
35
48
|
interface GeistdocsVersionSelectProps {
|
|
36
49
|
className?: string;
|
|
37
50
|
current?: string;
|
|
51
|
+
/**
|
|
52
|
+
* Existing paths per version ID, relative to each version's `routePrefix`.
|
|
53
|
+
* Compute server-side with `collectVersionSwitchPaths` (or
|
|
54
|
+
* `collectVersionPaths`) from `@vercel/geistdocs/source`. When provided,
|
|
55
|
+
* switching to a version that lacks the current page lands on the nearest
|
|
56
|
+
* existing ancestor (or the version's `fallbackPath`) instead of a 404.
|
|
57
|
+
*/
|
|
58
|
+
paths?: Record<string, GeistdocsVersionPaths | readonly string[]>;
|
|
38
59
|
versions: GeistdocsVersionConfig[] | GeistdocsVersionsConfig;
|
|
39
60
|
}
|
|
40
61
|
export declare const resolveRouteHref: <Item extends GeistdocsRouteSelectItem>({ currentItem, item, pathname, }: ResolveRouteHrefOptions<Item>) => string;
|
|
41
62
|
export declare const resolveVersionHref: ({ currentVersion, pathname, version, }: ResolveVersionHrefOptions) => string;
|
|
42
63
|
export declare const GeistdocsRouteSelect: <Item extends GeistdocsRouteSelectItem>({ ariaLabel, className, current, getDescription, items, renderIcon, }: GeistdocsRouteSelectProps<Item>) => import("react/jsx-runtime").JSX.Element | null;
|
|
43
|
-
export declare const GeistdocsVersionSelect: ({ className, current, versions, }: GeistdocsVersionSelectProps) => import("react/jsx-runtime").JSX.Element;
|
|
44
|
-
export {};
|
|
64
|
+
export declare const GeistdocsVersionSelect: ({ className, current, paths, versions, }: GeistdocsVersionSelectProps) => import("react/jsx-runtime").JSX.Element;
|
|
45
65
|
//# sourceMappingURL=versions.d.ts.map
|
package/dist/versions.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../src/versions.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;
|
|
1
|
+
{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../src/versions.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAQhF,OAAO,EACL,KAAK,qBAAqB,EAE3B,MAAM,6BAA6B,CAAC;AAErC,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEzE,MAAM,WAAW,wBAAwB;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,uBAAuB,CAAC,IAAI,SAAS,wBAAwB;IACrE,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,yBAAyB;IACjC,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED,UAAU,yBAAyB,CAAC,IAAI,SAAS,wBAAwB;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,KAAK,SAAS,CAAC;IACzE,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,KAAK,SAAS,CAAC;CACtE;AAED,UAAU,2BAA2B;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC;IAClE,QAAQ,EAAE,sBAAsB,EAAE,GAAG,uBAAuB,CAAC;CAC9D;AA0ED,eAAO,MAAM,gBAAgB,GAAI,IAAI,SAAS,wBAAwB,EAAE,kCAIrE,uBAAuB,CAAC,IAAI,CAAC,WA0B/B,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,wCAIhC,yBAAyB,WACgD,CAAC;AAE7E,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,wBAAwB,EAAE,uEAOzE,yBAAyB,CAAC,IAAI,CAAC,mDA0FjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,0CAKpC,2BAA2B,4CAwC7B,CAAC"}
|
package/dist/versions.js
CHANGED
|
@@ -4,6 +4,7 @@ import { ArchiveIcon, BoxIcon, CheckIcon, ChevronDownIcon } from "lucide-react";
|
|
|
4
4
|
import { usePathname, useRouter } from "next/navigation";
|
|
5
5
|
import { cn } from "./internal/cn";
|
|
6
6
|
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, } from "./internal/ui/dropdown-menu";
|
|
7
|
+
import { resolveVersionSwitchPath, } from "./internal/version-paths.js";
|
|
7
8
|
const LEADING_SLASH_PATTERN = /^\//;
|
|
8
9
|
const PATH_TOKEN_PATTERN = /:path\*|\*path/g;
|
|
9
10
|
const TRAILING_SLASH_PATTERN = /\/$/;
|
|
@@ -36,7 +37,14 @@ export const resolveRouteHref = ({ currentItem, item, pathname, }) => {
|
|
|
36
37
|
.replace(TRAILING_SLASH_PATTERN, "");
|
|
37
38
|
}
|
|
38
39
|
const routePrefix = item.routePrefix?.replace(TRAILING_SLASH_PATTERN, "") ?? "";
|
|
39
|
-
const
|
|
40
|
+
const targetPath = item.paths?.length
|
|
41
|
+
? (resolveVersionSwitchPath({
|
|
42
|
+
candidate: pathWithoutCurrentPrefix,
|
|
43
|
+
fallbackPath: item.fallbackPath,
|
|
44
|
+
paths: item.paths,
|
|
45
|
+
}) ?? pathWithoutCurrentPrefix)
|
|
46
|
+
: pathWithoutCurrentPrefix;
|
|
47
|
+
const href = `${routePrefix}${targetPath}`;
|
|
40
48
|
return href || "/";
|
|
41
49
|
};
|
|
42
50
|
export const resolveVersionHref = ({ currentVersion, pathname, version, }) => resolveRouteHref({ currentItem: currentVersion, item: version, pathname });
|
|
@@ -72,8 +80,23 @@ export const GeistdocsRouteSelect = ({ ariaLabel = "Select route", className, cu
|
|
|
72
80
|
return (_jsxs(DropdownMenuItem, { "aria-current": active ? "page" : undefined, className: "flex cursor-pointer items-center gap-2 rounded-md px-2 py-2", onSelect: () => navigateToItem(item), children: [renderIcon({ active, item }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-button-14 text-gray-1000", children: item.label }), description ? (_jsx("span", { className: "block truncate text-gray-900 text-label-13", children: description })) : null] }), active ? _jsx(CheckIcon, { className: "size-4 text-blue-900" }) : null] }, item.id));
|
|
73
81
|
}) })] }));
|
|
74
82
|
};
|
|
75
|
-
export const GeistdocsVersionSelect = ({ className, current, versions, }) => {
|
|
76
|
-
const
|
|
83
|
+
export const GeistdocsVersionSelect = ({ className, current, paths, versions, }) => {
|
|
84
|
+
const baseItems = Array.isArray(versions) ? versions : versions.items;
|
|
85
|
+
const items = paths
|
|
86
|
+
? baseItems.map((item) => {
|
|
87
|
+
const entry = paths[item.id];
|
|
88
|
+
if (!entry) {
|
|
89
|
+
return item;
|
|
90
|
+
}
|
|
91
|
+
return Array.isArray(entry)
|
|
92
|
+
? { ...item, paths: entry }
|
|
93
|
+
: {
|
|
94
|
+
...item,
|
|
95
|
+
fallbackPath: entry.fallbackPath,
|
|
96
|
+
paths: entry.paths,
|
|
97
|
+
};
|
|
98
|
+
})
|
|
99
|
+
: baseItems;
|
|
77
100
|
const currentId = current ?? (Array.isArray(versions) ? items[0]?.id : versions.current);
|
|
78
101
|
return (_jsx(GeistdocsRouteSelect, { ariaLabel: "Select documentation version", className: className, current: currentId, getDescription: ({ active, item }) => getVersionDescription({ current: active, version: item }), items: items, renderIcon: ({ active, item }) => item.icon ? (_jsx(SelectIcon, { active: active, children: item.icon })) : (_jsx(VersionIcon, { active: active })) }));
|
|
79
102
|
};
|
package/docs/agents.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Geistdocs Package Docs
|
|
2
2
|
|
|
3
|
-
These docs are bundled with `@vercel/geistdocs` 1.
|
|
3
|
+
These docs are bundled with `@vercel/geistdocs` 1.14.1 so agents can understand the installed package without web access.
|
|
4
4
|
They are generated from `apps/template/content/docs` during the package build.
|
|
5
5
|
|
|
6
6
|
## How to use these files
|
package/docs/llms.txt
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Geistdocs Package Documentation
|
|
2
2
|
|
|
3
|
-
These docs are bundled with `@vercel/geistdocs` 1.
|
|
3
|
+
These docs are bundled with `@vercel/geistdocs` 1.14.1.
|
|
4
4
|
They describe how to build package-backed Geistdocs sites and how to use the package APIs from generated project adapters.
|
|
5
5
|
|
|
6
6
|
## Documentation Index
|
|
@@ -526,6 +526,8 @@ export const geistdocsSource = createSource({
|
|
|
526
526
|
});
|
|
527
527
|
```
|
|
528
528
|
|
|
529
|
+
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.
|
|
530
|
+
|
|
529
531
|
## Add route adapters
|
|
530
532
|
|
|
531
533
|
Keep App Router files thin. Route files should call package helpers instead of copying package internals.
|
|
@@ -700,6 +702,8 @@ const proxy = createProxy({
|
|
|
700
702
|
});
|
|
701
703
|
```
|
|
702
704
|
|
|
705
|
+
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.
|
|
706
|
+
|
|
703
707
|
## Configure Tailwind CSS
|
|
704
708
|
|
|
705
709
|
Tailwind CSS v4 requires `@source` entries for package components and related dependencies.
|
|
@@ -938,6 +942,24 @@ export default defineGeistdocsSourceConfig();
|
|
|
938
942
|
|
|
939
943
|
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.
|
|
940
944
|
|
|
945
|
+
## Next.js base paths
|
|
946
|
+
|
|
947
|
+
When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
|
|
948
|
+
|
|
949
|
+
```ts title="next.config.ts"
|
|
950
|
+
const config: NextConfig = {
|
|
951
|
+
basePath: "/docs",
|
|
952
|
+
};
|
|
953
|
+
```
|
|
954
|
+
|
|
955
|
+
```tsx title="geistdocs.tsx"
|
|
956
|
+
export const basePath = "/docs";
|
|
957
|
+
```
|
|
958
|
+
|
|
959
|
+
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.
|
|
960
|
+
|
|
961
|
+
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`.
|
|
962
|
+
|
|
941
963
|
## Page actions
|
|
942
964
|
|
|
943
965
|
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`:
|
|
@@ -1031,7 +1053,11 @@ const docsPage = createDocsPage({
|
|
|
1031
1053
|
});
|
|
1032
1054
|
```
|
|
1033
1055
|
|
|
1034
|
-
Use `getPageUrl` when the
|
|
1056
|
+
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`.
|
|
1057
|
+
|
|
1058
|
+
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.
|
|
1059
|
+
|
|
1060
|
+
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.
|
|
1035
1061
|
|
|
1036
1062
|
## Package-owned runtime
|
|
1037
1063
|
|
|
@@ -1792,6 +1818,74 @@ For host-based versions, use `href` instead of `routePrefix`:
|
|
|
1792
1818
|
/>
|
|
1793
1819
|
```
|
|
1794
1820
|
|
|
1821
|
+
## Avoid 404s when switching versions
|
|
1822
|
+
|
|
1823
|
+
By default the selector swaps the route prefix without checking that the page
|
|
1824
|
+
exists in the target version, so pages that exist in only one version 404 on
|
|
1825
|
+
switch. Pass `paths` — computed server-side with `collectVersionSwitchPaths` —
|
|
1826
|
+
and the selector falls back to the nearest existing ancestor (or the version's
|
|
1827
|
+
docs root) instead:
|
|
1828
|
+
|
|
1829
|
+
```tsx title="app/[lang]/docs/layout.tsx"
|
|
1830
|
+
import { collectVersionSwitchPaths } from "@vercel/geistdocs/source";
|
|
1831
|
+
import { GeistdocsVersionSelect } from "@vercel/geistdocs/versions";
|
|
1832
|
+
import { config } from "@/lib/geistdocs/config";
|
|
1833
|
+
import { versions } from "@/lib/geistdocs/source";
|
|
1834
|
+
|
|
1835
|
+
const DocsLayout = async ({ children, params }) => {
|
|
1836
|
+
const { lang } = await params;
|
|
1837
|
+
|
|
1838
|
+
return (
|
|
1839
|
+
<GeistdocsDocsLayout
|
|
1840
|
+
config={config}
|
|
1841
|
+
sidebarTop={
|
|
1842
|
+
<GeistdocsVersionSelect
|
|
1843
|
+
current={versions.currentVersion}
|
|
1844
|
+
paths={collectVersionSwitchPaths({ lang, versions })}
|
|
1845
|
+
versions={config.versions}
|
|
1846
|
+
/>
|
|
1847
|
+
}
|
|
1848
|
+
tree={versions.current.source.pageTree[lang]}
|
|
1849
|
+
>
|
|
1850
|
+
{children}
|
|
1851
|
+
</GeistdocsDocsLayout>
|
|
1852
|
+
);
|
|
1853
|
+
};
|
|
1854
|
+
```
|
|
1855
|
+
|
|
1856
|
+
`collectVersionSwitchPaths` enumerates every page of every version from the
|
|
1857
|
+
`createVersionedSources` output and returns paths relative to each version's
|
|
1858
|
+
`routePrefix`, plus each version's docs root as the fallback landing page.
|
|
1859
|
+
|
|
1860
|
+
When an app rewrites loader URLs at render time (for example serving a
|
|
1861
|
+
`baseUrl: "/docs"` source under `/v5` with a custom `getPageUrl`), pass the
|
|
1862
|
+
same mapping so the collected paths match the public URLs. For sources that
|
|
1863
|
+
span several loaders per version (for example separate docs and cookbook
|
|
1864
|
+
sources), use the lower-level `collectVersionPaths` per version instead:
|
|
1865
|
+
|
|
1866
|
+
```tsx
|
|
1867
|
+
import { collectVersionPaths } from "@vercel/geistdocs/source";
|
|
1868
|
+
|
|
1869
|
+
const paths = {
|
|
1870
|
+
v4: {
|
|
1871
|
+
fallbackPath: "/docs",
|
|
1872
|
+
paths: collectVersionPaths({ lang, sources: [v4Docs, v4Cookbook] }),
|
|
1873
|
+
},
|
|
1874
|
+
v5: {
|
|
1875
|
+
fallbackPath: "/docs",
|
|
1876
|
+
paths: collectVersionPaths({
|
|
1877
|
+
lang,
|
|
1878
|
+
routePrefix: "/v5",
|
|
1879
|
+
sources: [v5Docs, v5Cookbook],
|
|
1880
|
+
}),
|
|
1881
|
+
},
|
|
1882
|
+
};
|
|
1883
|
+
```
|
|
1884
|
+
|
|
1885
|
+
Fallback resolution only applies to `routePrefix` versions. Host-based
|
|
1886
|
+
versions (`href`) always keep the plain path swap, since the target host's
|
|
1887
|
+
pages can't be enumerated locally.
|
|
1888
|
+
|
|
1795
1889
|
## Configure markdown routes
|
|
1796
1890
|
|
|
1797
1891
|
Each public route family needs a matching markdown route in `proxy.ts`. Read [Proxy and markdown routes](/docs/proxy) for the proxy configuration.
|
|
@@ -1927,6 +2021,8 @@ With these mappings:
|
|
|
1927
2021
|
|
|
1928
2022
|
Use `[lang]` in the destination when your markdown route is nested under `app/[lang]`. Use `*path` or `:path*` to insert the matched wildcard path.
|
|
1929
2023
|
|
|
2024
|
+
`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.
|
|
2025
|
+
|
|
1930
2026
|
## Root-mounted docs
|
|
1931
2027
|
|
|
1932
2028
|
For docs served from the site root, set the source `baseUrl` and config route to `/`:
|
|
@@ -1968,6 +2064,19 @@ const proxy = createProxy({
|
|
|
1968
2064
|
});
|
|
1969
2065
|
```
|
|
1970
2066
|
|
|
2067
|
+
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:
|
|
2068
|
+
|
|
2069
|
+
```ts title="proxy.ts"
|
|
2070
|
+
export const config = {
|
|
2071
|
+
matcher: [
|
|
2072
|
+
"/",
|
|
2073
|
+
"/((?!api(?:/|$)|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
|
|
2074
|
+
],
|
|
2075
|
+
};
|
|
2076
|
+
```
|
|
2077
|
+
|
|
2078
|
+
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.
|
|
2079
|
+
|
|
1971
2080
|
## Hook context
|
|
1972
2081
|
|
|
1973
2082
|
Both `before` and `after` receive the same context:
|
|
@@ -2027,6 +2136,10 @@ The `.mdx` version returns:
|
|
|
2027
2136
|
- The full processed Markdown content
|
|
2028
2137
|
- No HTML, styling, or navigation
|
|
2029
2138
|
|
|
2139
|
+
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`.
|
|
2140
|
+
|
|
2141
|
+
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.
|
|
2142
|
+
|
|
2030
2143
|
## Use cases
|
|
2031
2144
|
|
|
2032
2145
|
This feature is particularly useful for:
|
|
@@ -3081,6 +3194,8 @@ Users can subscribe to this URL using:
|
|
|
3081
3194
|
|
|
3082
3195
|
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.
|
|
3083
3196
|
|
|
3197
|
+
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.
|
|
3198
|
+
|
|
3084
3199
|
## Feed Format
|
|
3085
3200
|
|
|
3086
3201
|
The RSS feed follows the RSS 2.0 specification and includes:
|
package/docs/manifest.json
CHANGED
|
@@ -179,6 +179,24 @@ export default defineGeistdocsSourceConfig();
|
|
|
179
179
|
|
|
180
180
|
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.
|
|
181
181
|
|
|
182
|
+
## Next.js base paths
|
|
183
|
+
|
|
184
|
+
When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
|
|
185
|
+
|
|
186
|
+
```ts title="next.config.ts"
|
|
187
|
+
const config: NextConfig = {
|
|
188
|
+
basePath: "/docs",
|
|
189
|
+
};
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
```tsx title="geistdocs.tsx"
|
|
193
|
+
export const basePath = "/docs";
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
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.
|
|
197
|
+
|
|
198
|
+
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`.
|
|
199
|
+
|
|
182
200
|
## Page actions
|
|
183
201
|
|
|
184
202
|
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`:
|
|
@@ -272,7 +290,11 @@ const docsPage = createDocsPage({
|
|
|
272
290
|
});
|
|
273
291
|
```
|
|
274
292
|
|
|
275
|
-
Use `getPageUrl` when the
|
|
293
|
+
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`.
|
|
294
|
+
|
|
295
|
+
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.
|
|
296
|
+
|
|
297
|
+
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.
|
|
276
298
|
|
|
277
299
|
## Package-owned runtime
|
|
278
300
|
|
package/docs/pages/md.md
CHANGED
|
@@ -37,6 +37,10 @@ The `.mdx` version returns:
|
|
|
37
37
|
- The full processed Markdown content
|
|
38
38
|
- No HTML, styling, or navigation
|
|
39
39
|
|
|
40
|
+
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`.
|
|
41
|
+
|
|
42
|
+
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.
|
|
43
|
+
|
|
40
44
|
## Use cases
|
|
41
45
|
|
|
42
46
|
This feature is particularly useful for:
|