@vercel/geistdocs 2.15.4 → 2.16.0-canary.abbda54
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 +3 -3
- package/dist/config.d.ts.map +1 -1
- package/dist/internal/navbar/mobile-menu.d.ts +3 -3
- package/dist/internal/navbar/mobile-menu.d.ts.map +1 -1
- package/dist/internal/navbar/mobile-menu.js +3 -3
- package/dist/internal/navbar/navbar-logo.d.ts +5 -3
- package/dist/internal/navbar/navbar-logo.d.ts.map +1 -1
- package/dist/internal/navbar/navbar-logo.js +71 -14
- package/dist/navbar.js +4 -3
- package/dist/next.d.ts +15 -2
- package/dist/next.d.ts.map +1 -1
- package/dist/next.js +27 -5
- package/dist/routes/search.d.ts +8 -1
- package/dist/routes/search.d.ts.map +1 -1
- package/dist/routes/search.js +120 -82
- package/dist/source-config.d.ts +2 -0
- package/dist/source-config.d.ts.map +1 -1
- package/dist/source-config.js +2 -0
- package/docs/agents.md +1 -1
- package/docs/llms.txt +84 -2
- package/docs/manifest.json +1 -1
- package/docs/pages/configuration.md +83 -1
- package/package.json +22 -9
- package/rehype-code-highlights.d.ts +13 -0
- package/rehype-code-highlights.js +278 -0
- package/search-index.d.ts +14 -0
- package/search-index.js +447 -0
- package/source-config-public.d.ts +15 -0
- package/source-config-public.js +47 -0
- package/source-config.js +2 -0
- package/template/AGENTS.md +4 -0
- package/template/app/api/search/route.ts +7 -2
- package/template/content/docs/configuration.mdx +83 -1
- package/template/lib/geistdocs/search-source.ts +6 -0
- package/template/next.config.ts +1 -1
- package/template/package.json +1 -1
- package/template/source.config.ts +1 -1
package/search-index.js
ADDED
|
@@ -0,0 +1,447 @@
|
|
|
1
|
+
import {
|
|
2
|
+
mkdir,
|
|
3
|
+
readdir,
|
|
4
|
+
readFile,
|
|
5
|
+
rename,
|
|
6
|
+
rm,
|
|
7
|
+
writeFile,
|
|
8
|
+
} from "node:fs/promises";
|
|
9
|
+
import path from "node:path";
|
|
10
|
+
import { createProcessor } from "@mdx-js/mdx";
|
|
11
|
+
import { remarkInclude } from "fumadocs-mdx/config";
|
|
12
|
+
import { load } from "js-yaml";
|
|
13
|
+
import { glob } from "tinyglobby";
|
|
14
|
+
import { visit } from "unist-util-visit";
|
|
15
|
+
import { VFile } from "vfile";
|
|
16
|
+
|
|
17
|
+
const FRONTMATTER = /^---\r?\n(.+?)\r?\n---\r?\n/s;
|
|
18
|
+
const PLUGIN_NAME = "geistdocs-search-index";
|
|
19
|
+
const flatten = (node) =>
|
|
20
|
+
"children" in node ? node.children.map(flatten).join("") : (node.value ?? "");
|
|
21
|
+
|
|
22
|
+
// Search uses the remark output, before HTML/highlighting and JS generation.
|
|
23
|
+
// Mirror Fumadocs' heading-derived title before discarding the rendered body.
|
|
24
|
+
const finishSearch = () => (tree, file) => {
|
|
25
|
+
if (!file.data.frontmatter.title) {
|
|
26
|
+
visit(tree, "heading", (node) => {
|
|
27
|
+
if (node.depth === 1) {
|
|
28
|
+
file.data.frontmatter.title = flatten(node);
|
|
29
|
+
return false;
|
|
30
|
+
}
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
tree.children = [];
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
const serialize = (files) => {
|
|
37
|
+
const dates = [];
|
|
38
|
+
const walk = (value, keys = []) => {
|
|
39
|
+
if (value instanceof Date) {
|
|
40
|
+
dates.push(keys);
|
|
41
|
+
return value.toISOString();
|
|
42
|
+
}
|
|
43
|
+
if (Array.isArray(value)) {
|
|
44
|
+
return value.map((item, index) => walk(item, [...keys, index]));
|
|
45
|
+
}
|
|
46
|
+
if (value && typeof value === "object") {
|
|
47
|
+
if (Object.getPrototypeOf(value) !== Object.prototype) {
|
|
48
|
+
throw new TypeError(
|
|
49
|
+
"Search metadata must contain only JSON values and Dates."
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
return Object.fromEntries(
|
|
53
|
+
Object.entries(value).map(([key, item]) => [
|
|
54
|
+
key,
|
|
55
|
+
walk(item, [...keys, key]),
|
|
56
|
+
])
|
|
57
|
+
);
|
|
58
|
+
}
|
|
59
|
+
if (
|
|
60
|
+
typeof value === "function" ||
|
|
61
|
+
typeof value === "symbol" ||
|
|
62
|
+
typeof value === "bigint"
|
|
63
|
+
) {
|
|
64
|
+
throw new TypeError(
|
|
65
|
+
"Search metadata must contain only JSON values and Dates."
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
return value;
|
|
69
|
+
};
|
|
70
|
+
const json = JSON.stringify(walk(files));
|
|
71
|
+
return [
|
|
72
|
+
"// Generated by Geistdocs. Search data only; no MDX imports.",
|
|
73
|
+
"// @ts-nocheck",
|
|
74
|
+
'import "server-only";',
|
|
75
|
+
`const files = JSON.parse(${JSON.stringify(json)});`,
|
|
76
|
+
...(dates.length
|
|
77
|
+
? [
|
|
78
|
+
`for (const keys of ${JSON.stringify(dates)}) {`,
|
|
79
|
+
" let target = files;",
|
|
80
|
+
" for (const key of keys.slice(0, -1)) target = target[key];",
|
|
81
|
+
" const key = keys[keys.length - 1];",
|
|
82
|
+
" target[key] = new Date(target[key]);",
|
|
83
|
+
"}",
|
|
84
|
+
]
|
|
85
|
+
: []),
|
|
86
|
+
'export default { toFumadocsSource: (): import("fumadocs-core/source").Source => ({ files }) };',
|
|
87
|
+
"",
|
|
88
|
+
].join("\n");
|
|
89
|
+
};
|
|
90
|
+
|
|
91
|
+
const trackIncludes = (tree, filePath, dependencies) => {
|
|
92
|
+
visit(tree, (node) => {
|
|
93
|
+
if (node.name !== "include") {
|
|
94
|
+
return;
|
|
95
|
+
}
|
|
96
|
+
const specifier = flatten(node);
|
|
97
|
+
if (!specifier) {
|
|
98
|
+
return;
|
|
99
|
+
}
|
|
100
|
+
const hash = specifier.lastIndexOf("#");
|
|
101
|
+
const file = hash < 0 ? specifier : specifier.slice(0, hash);
|
|
102
|
+
const cwd = Array.isArray(node.attributes)
|
|
103
|
+
? node.attributes.some(
|
|
104
|
+
(attribute) =>
|
|
105
|
+
attribute.type === "mdxJsxAttribute" &&
|
|
106
|
+
attribute.name === "cwd" &&
|
|
107
|
+
(typeof attribute.value === "string" || attribute.value === null)
|
|
108
|
+
)
|
|
109
|
+
: Object.hasOwn(node.attributes ?? {}, "cwd");
|
|
110
|
+
dependencies.add(
|
|
111
|
+
path.resolve(cwd ? process.cwd() : path.dirname(filePath), file)
|
|
112
|
+
);
|
|
113
|
+
});
|
|
114
|
+
};
|
|
115
|
+
|
|
116
|
+
const createProcessors = (options, dependencies) => {
|
|
117
|
+
const processors = new Map();
|
|
118
|
+
return function getProcessor(format) {
|
|
119
|
+
if (!processors.has(format)) {
|
|
120
|
+
const processor = createProcessor({
|
|
121
|
+
...options,
|
|
122
|
+
format,
|
|
123
|
+
remarkPlugins: [
|
|
124
|
+
remarkInclude,
|
|
125
|
+
...(options.remarkPlugins ?? []),
|
|
126
|
+
finishSearch,
|
|
127
|
+
],
|
|
128
|
+
rehypePlugins: [],
|
|
129
|
+
recmaPlugins: [],
|
|
130
|
+
});
|
|
131
|
+
const parse = processor.parse.bind(processor);
|
|
132
|
+
processor.parse = (file) => {
|
|
133
|
+
const tree = parse(file);
|
|
134
|
+
// Fumadocs registers includes after reading them. Track them during
|
|
135
|
+
// parsing too so creating a previously missing snippet can recover.
|
|
136
|
+
if (typeof file?.path === "string") {
|
|
137
|
+
trackIncludes(tree, file.path, dependencies);
|
|
138
|
+
}
|
|
139
|
+
return tree;
|
|
140
|
+
};
|
|
141
|
+
processors.set(format, processor);
|
|
142
|
+
}
|
|
143
|
+
return processors.get(format);
|
|
144
|
+
};
|
|
145
|
+
};
|
|
146
|
+
|
|
147
|
+
const collectPage = async (
|
|
148
|
+
context,
|
|
149
|
+
collection,
|
|
150
|
+
relativePath,
|
|
151
|
+
getProcessor,
|
|
152
|
+
dependencies,
|
|
153
|
+
passthroughs
|
|
154
|
+
) => {
|
|
155
|
+
const filePath = path.join(collection.dir, relativePath);
|
|
156
|
+
dependencies.add(path.resolve(filePath));
|
|
157
|
+
const source = await readFile(filePath, "utf8");
|
|
158
|
+
const match = source.match(FRONTMATTER);
|
|
159
|
+
const frontmatter = await context.core.transformFrontmatter(
|
|
160
|
+
{ collection, filePath, source },
|
|
161
|
+
match ? (load(match[1]) ?? {}) : {}
|
|
162
|
+
);
|
|
163
|
+
const content = match ? source.slice(match[0].length) : source;
|
|
164
|
+
const compiler = {
|
|
165
|
+
addDependency(file) {
|
|
166
|
+
dependencies.add(path.resolve(file));
|
|
167
|
+
},
|
|
168
|
+
};
|
|
169
|
+
let file = new VFile({
|
|
170
|
+
path: filePath,
|
|
171
|
+
value: content,
|
|
172
|
+
data: {
|
|
173
|
+
frontmatter,
|
|
174
|
+
_compiler: compiler,
|
|
175
|
+
_getProcessor: getProcessor,
|
|
176
|
+
},
|
|
177
|
+
});
|
|
178
|
+
file = await context.core.transformVFile(
|
|
179
|
+
{ collection, filePath, source: content },
|
|
180
|
+
file
|
|
181
|
+
);
|
|
182
|
+
const processor = getProcessor(filePath.endsWith(".mdx") ? "mdx" : "md");
|
|
183
|
+
await processor.run(processor.parse(file), file);
|
|
184
|
+
if (!file.data.structuredData) {
|
|
185
|
+
throw new Error(
|
|
186
|
+
`${filePath}: searchIndex requires remarkStructure to produce search data.`
|
|
187
|
+
);
|
|
188
|
+
}
|
|
189
|
+
const extra = Object.fromEntries(
|
|
190
|
+
(file.data["mdx-export"] ?? [])
|
|
191
|
+
.filter((entry) => passthroughs.includes(entry.name))
|
|
192
|
+
.map((entry) => [entry.name, entry.value])
|
|
193
|
+
);
|
|
194
|
+
return {
|
|
195
|
+
type: "page",
|
|
196
|
+
path: relativePath,
|
|
197
|
+
absolutePath: filePath,
|
|
198
|
+
data: {
|
|
199
|
+
structuredData: file.data.structuredData,
|
|
200
|
+
...extra,
|
|
201
|
+
...file.data.frontmatter,
|
|
202
|
+
info: { path: relativePath, fullPath: filePath },
|
|
203
|
+
},
|
|
204
|
+
};
|
|
205
|
+
};
|
|
206
|
+
|
|
207
|
+
const collectMeta = async (context, collection, relativePath, dependencies) => {
|
|
208
|
+
const filePath = path.join(collection.dir, relativePath);
|
|
209
|
+
dependencies.add(path.resolve(filePath));
|
|
210
|
+
const source = await readFile(filePath, "utf8");
|
|
211
|
+
const data = filePath.endsWith(".json") ? JSON.parse(source) : load(source);
|
|
212
|
+
return {
|
|
213
|
+
type: "meta",
|
|
214
|
+
path: relativePath,
|
|
215
|
+
absolutePath: filePath,
|
|
216
|
+
data: await context.core.transformMeta(
|
|
217
|
+
{ collection, filePath, source },
|
|
218
|
+
data
|
|
219
|
+
),
|
|
220
|
+
};
|
|
221
|
+
};
|
|
222
|
+
|
|
223
|
+
const COLLECTION_NAME = /^[\w$-]+$/;
|
|
224
|
+
const collectCollection = async (
|
|
225
|
+
context,
|
|
226
|
+
parent,
|
|
227
|
+
dependencies,
|
|
228
|
+
passthroughs
|
|
229
|
+
) => {
|
|
230
|
+
// Collection names become paths, never allow output outside search/.
|
|
231
|
+
if (!COLLECTION_NAME.test(parent.name)) {
|
|
232
|
+
throw new Error(`Invalid search collection name: ${parent.name}`);
|
|
233
|
+
}
|
|
234
|
+
const collection = parent.type === "docs" ? parent.docs : parent;
|
|
235
|
+
const options = await context.core
|
|
236
|
+
.getConfig()
|
|
237
|
+
.getMDXOptions(collection, "bundler");
|
|
238
|
+
const getProcessor = createProcessors(options, dependencies);
|
|
239
|
+
const files = [];
|
|
240
|
+
// Keep Fumadocs' glob order: insertion order breaks equal-score ties.
|
|
241
|
+
for (const file of await glob(collection.patterns, { cwd: collection.dir })) {
|
|
242
|
+
files.push(
|
|
243
|
+
await collectPage(
|
|
244
|
+
context,
|
|
245
|
+
collection,
|
|
246
|
+
file,
|
|
247
|
+
getProcessor,
|
|
248
|
+
dependencies,
|
|
249
|
+
passthroughs
|
|
250
|
+
)
|
|
251
|
+
);
|
|
252
|
+
}
|
|
253
|
+
if (parent.type === "docs") {
|
|
254
|
+
for (const file of await glob(parent.meta.patterns, {
|
|
255
|
+
cwd: parent.meta.dir,
|
|
256
|
+
})) {
|
|
257
|
+
files.push(await collectMeta(context, parent.meta, file, dependencies));
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
return { path: `search/${parent.name}.ts`, content: serialize(files) };
|
|
261
|
+
};
|
|
262
|
+
|
|
263
|
+
const removeObsolete = async (outDir, entries) => {
|
|
264
|
+
const current = new Set(entries.map((entry) => path.basename(entry.path)));
|
|
265
|
+
const output = path.join(outDir, "search");
|
|
266
|
+
const existing = await readdir(output).catch((error) => {
|
|
267
|
+
if (error.code === "ENOENT") {
|
|
268
|
+
return [];
|
|
269
|
+
}
|
|
270
|
+
throw error;
|
|
271
|
+
});
|
|
272
|
+
for (const file of existing) {
|
|
273
|
+
if (file.endsWith(".ts") && !current.has(file)) {
|
|
274
|
+
await rm(path.join(output, file));
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
};
|
|
278
|
+
|
|
279
|
+
// The source config is bundled separately by Fumadocs. A process-wide key lets
|
|
280
|
+
// the Next wrapper await failures and keeps config reloads in the same queue.
|
|
281
|
+
const STATE_KEY = Symbol.for("@vercel/geistdocs/search-index");
|
|
282
|
+
const getState = ({ configPath = "source.config.ts", outDir = ".source" }) => {
|
|
283
|
+
globalThis[STATE_KEY] ??= new Map();
|
|
284
|
+
const states = globalThis[STATE_KEY];
|
|
285
|
+
const key = `${path.resolve(configPath)}:${path.resolve(outDir)}`;
|
|
286
|
+
if (!states.has(key)) {
|
|
287
|
+
states.set(key, { revision: 0, queue: Promise.resolve() });
|
|
288
|
+
}
|
|
289
|
+
return states.get(key);
|
|
290
|
+
};
|
|
291
|
+
|
|
292
|
+
/** Internal Next integration: production servers consume existing artifacts. */
|
|
293
|
+
export const skipSearchIndexGeneration = (options = {}) => {
|
|
294
|
+
getState(options).skip = true;
|
|
295
|
+
};
|
|
296
|
+
|
|
297
|
+
/** Internal Next integration: public Fumadocs codegen, with emit errors propagated. */
|
|
298
|
+
export const prepareSearchIndex = async (options = {}) => {
|
|
299
|
+
const state = getState(options);
|
|
300
|
+
state.skip = false;
|
|
301
|
+
state.captureErrors = true;
|
|
302
|
+
state.error = undefined;
|
|
303
|
+
try {
|
|
304
|
+
const { postInstall } = await import("fumadocs-mdx/next");
|
|
305
|
+
await postInstall({
|
|
306
|
+
...options,
|
|
307
|
+
configPath: path.resolve(options.configPath ?? "source.config.ts"),
|
|
308
|
+
outDir: path.resolve(options.outDir ?? ".source"),
|
|
309
|
+
});
|
|
310
|
+
if (state.error) {
|
|
311
|
+
throw state.error;
|
|
312
|
+
}
|
|
313
|
+
} finally {
|
|
314
|
+
state.captureErrors = false;
|
|
315
|
+
}
|
|
316
|
+
};
|
|
317
|
+
|
|
318
|
+
const writeEntries = async (context, entries) => {
|
|
319
|
+
await mkdir(path.join(context.outDir, "search"), { recursive: true });
|
|
320
|
+
for (const entry of entries) {
|
|
321
|
+
const target = path.join(context.outDir, entry.path);
|
|
322
|
+
// Keep watchers from reading a partially written module; avoid HMR churn
|
|
323
|
+
// when Next's own initialization regenerates the same data.
|
|
324
|
+
if (
|
|
325
|
+
(await readFile(target, "utf8").catch(() => undefined)) === entry.content
|
|
326
|
+
) {
|
|
327
|
+
continue;
|
|
328
|
+
}
|
|
329
|
+
const temporary = `${target}.${process.pid}.tmp`;
|
|
330
|
+
await writeFile(temporary, entry.content);
|
|
331
|
+
await rename(temporary, target);
|
|
332
|
+
}
|
|
333
|
+
await removeObsolete(context.outDir, entries);
|
|
334
|
+
};
|
|
335
|
+
|
|
336
|
+
const collectEntries = async (context, dependencies) => {
|
|
337
|
+
const serverOptions = {};
|
|
338
|
+
for (const plugin of context.core.getPlugins()) {
|
|
339
|
+
plugin["index-file"]?.serverOptions?.call(context, serverOptions);
|
|
340
|
+
}
|
|
341
|
+
const entries = [];
|
|
342
|
+
for (const collection of context.core.getConfig().collectionList) {
|
|
343
|
+
if (collection.type === "docs" || collection.type === "doc") {
|
|
344
|
+
entries.push(
|
|
345
|
+
await collectCollection(
|
|
346
|
+
context,
|
|
347
|
+
collection,
|
|
348
|
+
dependencies,
|
|
349
|
+
serverOptions.doc?.passthroughs ?? []
|
|
350
|
+
)
|
|
351
|
+
);
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
return entries;
|
|
355
|
+
};
|
|
356
|
+
|
|
357
|
+
const recordFailure = (state, error) => {
|
|
358
|
+
if (state.captureErrors) {
|
|
359
|
+
state.error = error;
|
|
360
|
+
} else if (process.env.NODE_ENV !== "development") {
|
|
361
|
+
process.exitCode = 1;
|
|
362
|
+
}
|
|
363
|
+
};
|
|
364
|
+
|
|
365
|
+
/** Fumadocs plugin: emits .source/search/<collection>.ts before bundling. */
|
|
366
|
+
export const searchIndex = () => {
|
|
367
|
+
let dependencies = new Set();
|
|
368
|
+
let revision;
|
|
369
|
+
return {
|
|
370
|
+
name: PLUGIN_NAME,
|
|
371
|
+
config() {
|
|
372
|
+
revision = undefined;
|
|
373
|
+
},
|
|
374
|
+
emit() {
|
|
375
|
+
const state = getState(this);
|
|
376
|
+
if (state.skip) {
|
|
377
|
+
return Promise.resolve([]);
|
|
378
|
+
}
|
|
379
|
+
revision ??= ++state.revision;
|
|
380
|
+
const generation = revision;
|
|
381
|
+
const run = state.queue.then(async () => {
|
|
382
|
+
if (generation !== state.revision) {
|
|
383
|
+
return [];
|
|
384
|
+
}
|
|
385
|
+
const nextDependencies = new Set();
|
|
386
|
+
try {
|
|
387
|
+
const entries = await collectEntries(this, nextDependencies);
|
|
388
|
+
if (generation !== state.revision) {
|
|
389
|
+
return [];
|
|
390
|
+
}
|
|
391
|
+
dependencies = nextDependencies;
|
|
392
|
+
await writeEntries(this, entries);
|
|
393
|
+
// Writes stay inside the queue so old config emissions cannot
|
|
394
|
+
// overwrite files after the new config has finished generating.
|
|
395
|
+
return [];
|
|
396
|
+
} catch (error) {
|
|
397
|
+
if (generation !== state.revision) {
|
|
398
|
+
return [];
|
|
399
|
+
}
|
|
400
|
+
dependencies = new Set([...dependencies, ...nextDependencies]);
|
|
401
|
+
recordFailure(state, error);
|
|
402
|
+
await rm(path.join(this.outDir, "search"), {
|
|
403
|
+
recursive: true,
|
|
404
|
+
force: true,
|
|
405
|
+
});
|
|
406
|
+
throw error;
|
|
407
|
+
}
|
|
408
|
+
});
|
|
409
|
+
state.queue = run.then(
|
|
410
|
+
() => undefined,
|
|
411
|
+
() => undefined
|
|
412
|
+
);
|
|
413
|
+
return run;
|
|
414
|
+
},
|
|
415
|
+
configureServer({ watcher }) {
|
|
416
|
+
if (!watcher) {
|
|
417
|
+
return;
|
|
418
|
+
}
|
|
419
|
+
watcher.add([...dependencies]);
|
|
420
|
+
let timer;
|
|
421
|
+
watcher.on("all", (_event, file) => {
|
|
422
|
+
if (
|
|
423
|
+
!(
|
|
424
|
+
dependencies.has(path.resolve(file)) ||
|
|
425
|
+
this.core
|
|
426
|
+
.getConfig()
|
|
427
|
+
.collectionList.some((collection) => collection.hasFile(file))
|
|
428
|
+
)
|
|
429
|
+
) {
|
|
430
|
+
return;
|
|
431
|
+
}
|
|
432
|
+
clearTimeout(timer);
|
|
433
|
+
timer = setTimeout(async () => {
|
|
434
|
+
try {
|
|
435
|
+
await this.core.emitAndWrite({
|
|
436
|
+
filterPlugin: (plugin) => plugin.name === PLUGIN_NAME,
|
|
437
|
+
});
|
|
438
|
+
} catch (error) {
|
|
439
|
+
console.error("[geistdocs search-index]", error);
|
|
440
|
+
} finally {
|
|
441
|
+
watcher.add([...dependencies]);
|
|
442
|
+
}
|
|
443
|
+
}, 50);
|
|
444
|
+
});
|
|
445
|
+
},
|
|
446
|
+
};
|
|
447
|
+
};
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type {
|
|
2
|
+
GeistdocsSourceConfigOptions as BaseOptions,
|
|
3
|
+
defineGeistdocsSourceConfig as defineBaseConfig,
|
|
4
|
+
} from "./dist/source-config.js";
|
|
5
|
+
|
|
6
|
+
export * from "./dist/source-config.js";
|
|
7
|
+
|
|
8
|
+
export interface GeistdocsSourceConfigOptions extends BaseOptions {
|
|
9
|
+
/** Public package only. Defaults to Highlights; false disables highlighting. */
|
|
10
|
+
highlighter?: "highlights" | "shiki" | false;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export declare const defineGeistdocsSourceConfig: (
|
|
14
|
+
options?: GeistdocsSourceConfigOptions
|
|
15
|
+
) => ReturnType<typeof defineBaseConfig>;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { rehypeCodeHighlights } from "./rehype-code-highlights.js";
|
|
2
|
+
import { defineGeistdocsSourceConfig as defineBaseConfig } from "./source-config.js";
|
|
3
|
+
|
|
4
|
+
// biome-ignore lint/performance/noBarrelFile: this package entry point reuses the already-loaded source config.
|
|
5
|
+
export * from "./source-config.js";
|
|
6
|
+
|
|
7
|
+
// Keep the shared source config on Shiki: the private product copies that
|
|
8
|
+
// entry point and must not acquire a dependency on Highlights.
|
|
9
|
+
export const defineGeistdocsSourceConfig = (options = {}) => {
|
|
10
|
+
const { highlighter = "highlights", ...config } = options;
|
|
11
|
+
if (!["highlights", "shiki", false].includes(highlighter)) {
|
|
12
|
+
throw new TypeError(`Unknown code highlighter: ${highlighter}`);
|
|
13
|
+
}
|
|
14
|
+
const result = defineBaseConfig(config);
|
|
15
|
+
const mdx = result.mdxOptions;
|
|
16
|
+
if (highlighter === false || config.mdxOptions?.rehypeCodeOptions === false) {
|
|
17
|
+
mdx.rehypeCodeOptions = false;
|
|
18
|
+
return result;
|
|
19
|
+
}
|
|
20
|
+
if (highlighter === "shiki") {
|
|
21
|
+
return result;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
const plugins = mdx.rehypePlugins;
|
|
25
|
+
if (typeof plugins === "function") {
|
|
26
|
+
mdx.rehypePlugins = (defaults) => {
|
|
27
|
+
// Fumadocs 14 puts its enabled code highlighter first. Capture the
|
|
28
|
+
// loader's instance before the consumer can reorder or remove it;
|
|
29
|
+
// pnpm may give Geistdocs a different copy of fumadocs-core.
|
|
30
|
+
const first = defaults[0];
|
|
31
|
+
const defaultHighlighter = Array.isArray(first) ? first[0] : first;
|
|
32
|
+
return plugins(defaults).map((entry) => {
|
|
33
|
+
const [plugin, pluginOptions] = Array.isArray(entry) ? entry : [entry];
|
|
34
|
+
return defaultHighlighter && plugin === defaultHighlighter
|
|
35
|
+
? [rehypeCodeHighlights, pluginOptions]
|
|
36
|
+
: entry;
|
|
37
|
+
});
|
|
38
|
+
};
|
|
39
|
+
} else {
|
|
40
|
+
mdx.rehypePlugins = [
|
|
41
|
+
[rehypeCodeHighlights, mdx.rehypeCodeOptions],
|
|
42
|
+
...(plugins ?? []),
|
|
43
|
+
];
|
|
44
|
+
mdx.rehypeCodeOptions = false;
|
|
45
|
+
}
|
|
46
|
+
return result;
|
|
47
|
+
};
|
package/source-config.js
CHANGED
|
@@ -17,6 +17,7 @@ import lastModified from "fumadocs-mdx/plugins/last-modified";
|
|
|
17
17
|
import { z } from "zod";
|
|
18
18
|
import { rehypeTaskListLabels } from "./rehype-task-list-labels.js";
|
|
19
19
|
import { remarkDetails } from "./remark-details.js";
|
|
20
|
+
import { searchIndex } from "./search-index.js";
|
|
20
21
|
|
|
21
22
|
// Mirrors src/internal/last-modified.ts. This file must stay dependency-free
|
|
22
23
|
// on dist so source.config.ts can load it before the package is built.
|
|
@@ -307,6 +308,7 @@ export const defineGeistdocsSourceConfig = (config = {}) => {
|
|
|
307
308
|
plugins: [
|
|
308
309
|
lastModified({ versionControl: getLastModified }),
|
|
309
310
|
...existingPlugins,
|
|
311
|
+
...(config.searchIndex ? [searchIndex()] : []),
|
|
310
312
|
],
|
|
311
313
|
});
|
|
312
314
|
};
|
package/template/AGENTS.md
CHANGED
|
@@ -108,6 +108,10 @@ Use these instructions when an AI coding agent edits this project.
|
|
|
108
108
|
- On a canary project, `geistdocs update` follows the current `canary` dist-tag. Check and test that version before updating an active migration.
|
|
109
109
|
- Review dependency changes and run the verification commands before committing an update.
|
|
110
110
|
|
|
111
|
+
## Search data
|
|
112
|
+
|
|
113
|
+
- Keep `searchIndex: true` in both source config and `createGeistdocs` in Next config and the search route's lazy import of `lib/geistdocs/search-source`. That module uses `.source/search/docs`; importing `.source/server` there restores the compiled-MDX cold-start cost. Share source options without sharing the rendering source import. Search-only collections do not render pages or produce Markdown.
|
|
114
|
+
|
|
111
115
|
## Commands
|
|
112
116
|
|
|
113
117
|
- Start development: `pnpm dev`
|
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
import { createSearchRoute } from "@vercel/geistdocs/routes/search";
|
|
2
2
|
import { config } from "@/lib/geistdocs/config";
|
|
3
|
-
import { geistdocsSource } from "@/lib/geistdocs/source";
|
|
4
3
|
|
|
5
|
-
export const GET = createSearchRoute({
|
|
4
|
+
export const GET = createSearchRoute({
|
|
5
|
+
config,
|
|
6
|
+
loadSources: async () => {
|
|
7
|
+
const { searchSource } = await import("@/lib/geistdocs/search-source");
|
|
8
|
+
return [searchSource];
|
|
9
|
+
},
|
|
10
|
+
});
|
|
@@ -103,7 +103,7 @@ export const navbarBrand: GeistdocsNavbarBrand = "labs";
|
|
|
103
103
|
|
|
104
104
|
The generated `lib/geistdocs/config.tsx` forwards this export to `defineConfig`. Existing sites can forward it in their adapter or set `navbarBrand: "labs"` directly in `defineConfig`. Private projects use the type from `@vercel/geistdocs-private/config`.
|
|
105
105
|
|
|
106
|
-
Labs links to [vercel.com/labs](https://vercel.com/labs) and adapts to light and dark themes.
|
|
106
|
+
Labs links to [vercel.com/labs](https://vercel.com/labs) and adapts to light and dark themes. Set `navbarVariant: "vercel-labs"` in `defineConfig` to use the Labs mark and show the Labs products and experiments menu. The previous `"standard"` value remains supported as an alias for `"vercel"`. The `"oss"` (default) layout keeps your project's `Logo` and `logoHref` separate from the brand and shows the OSS product menu. The `"vercel"` layout shows the selected brand mark, with no separator, project logo, or product menu.
|
|
107
107
|
|
|
108
108
|
For new projects, both CLIs accept `--brand labs`; omitting it or using `--brand vercel` preserves the defaults. See [Create a Labs starter](/docs/getting-started#create-a-labs-starter).
|
|
109
109
|
|
|
@@ -283,6 +283,88 @@ export const docs = defineDocs({
|
|
|
283
283
|
export default defineGeistdocsSourceConfig();
|
|
284
284
|
```
|
|
285
285
|
|
|
286
|
+
### Search-only collections
|
|
287
|
+
|
|
288
|
+
Enable generation of search data without compiled page bodies:
|
|
289
|
+
|
|
290
|
+
```ts title="source.config.ts"
|
|
291
|
+
export default defineGeistdocsSourceConfig({ searchIndex: true });
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
Also enable preparation in the Next wrapper. It waits for codegen before bundling
|
|
295
|
+
and skips source extraction in `next start`:
|
|
296
|
+
|
|
297
|
+
```ts title="next.config.ts"
|
|
298
|
+
const withGeistdocs = createGeistdocs({ searchIndex: true });
|
|
299
|
+
export default withGeistdocs(config);
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
With this option, the wrapper returns a phase-aware Next config function. Export
|
|
303
|
+
it directly as above; apply other Next config wrappers to `config` first.
|
|
304
|
+
|
|
305
|
+
Run your existing `fumadocs-mdx` postinstall command to generate
|
|
306
|
+
`.source/search/<collection>.ts`. Each module exports a collection compatible
|
|
307
|
+
with `createSource`; its frontmatter, sections, and metadata contain no MDX
|
|
308
|
+
imports. Keep the same source options (base URL, slugs, locales, page-tree
|
|
309
|
+
customization) as your rendering source, in a shared module that does not import
|
|
310
|
+
`.source/server`.
|
|
311
|
+
|
|
312
|
+
```ts title="lib/geistdocs/search-source.ts"
|
|
313
|
+
import { createSource } from "@vercel/geistdocs/source";
|
|
314
|
+
import docs from "@/.source/search/docs";
|
|
315
|
+
import { config } from "./config";
|
|
316
|
+
|
|
317
|
+
export const searchSource = createSource({ docs, config });
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
```ts title="app/api/search/route.ts"
|
|
321
|
+
import { createSearchRoute } from "@vercel/geistdocs/routes/search";
|
|
322
|
+
import { config } from "@/lib/geistdocs/config";
|
|
323
|
+
|
|
324
|
+
export const GET = createSearchRoute({
|
|
325
|
+
config,
|
|
326
|
+
loadSources: async () => {
|
|
327
|
+
const { searchSource } = await import("@/lib/geistdocs/search-source");
|
|
328
|
+
return [searchSource];
|
|
329
|
+
},
|
|
330
|
+
});
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
Use either `loadSources` or the existing `source`/`sources` options. Concurrent
|
|
334
|
+
requests share initialization; a failed initialization can be retried. Only the
|
|
335
|
+
requested locale's indexes are built. For versioned sites, create one lazy route
|
|
336
|
+
per version and dispatch to it using your existing version selector. Do not
|
|
337
|
+
import a barrel that also loads the rendering sources.
|
|
338
|
+
|
|
339
|
+
The generator runs the collection's schemas, frontmatter/VFile/metadata hooks,
|
|
340
|
+
and resolved remark plugins, including Markdown includes. It skips highlighting,
|
|
341
|
+
rehype, and recma, and adds a separate remark pass during codegen. Custom search
|
|
342
|
+
content must be recorded in `structuredData` by the remark pipeline. Collection
|
|
343
|
+
MDX overrides must retain `remarkStructure`. Metadata must serialize as JSON
|
|
344
|
+
values or Dates; custom runtime exports, page bodies, and Markdown methods are
|
|
345
|
+
not available on search-only pages. Filters must use stable metadata, not render
|
|
346
|
+
or load page bodies. Keep generated modules server-only: internal pages and
|
|
347
|
+
custom metadata may be present, with `internal`, `excludeFrom`, and `filterPage`
|
|
348
|
+
applied by the search route before returning results.
|
|
349
|
+
|
|
350
|
+
This works in development, previews, and production, in both packages. Content,
|
|
351
|
+
metadata, and registered include dependencies regenerate on edits; generation
|
|
352
|
+
errors invalidate old output and fail production/codegen commands. Orama still
|
|
353
|
+
builds its indexes on first search. Keep `.source/server` for docs rendering,
|
|
354
|
+
Markdown exports, and chat.
|
|
355
|
+
|
|
356
|
+
### Code highlighter (public package)
|
|
357
|
+
|
|
358
|
+
The public package uses [Highlights](https://diffs.com/highlights), which tokenizes code with WebAssembly lexers while keeping the JavaScript MDX compiler. Geist colors, titles, icons, tabs and `[!code ...]` annotations are preserved. Some token colors differ from Shiki, and unsupported languages render as plain text. To use Shiki's TextMate grammars instead, pass `highlighter: "shiki"`:
|
|
359
|
+
|
|
360
|
+
```ts title="source.config.ts"
|
|
361
|
+
export default defineGeistdocsSourceConfig({ highlighter: "shiki" });
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
Set `highlighter: false` or `mdxOptions.rehypeCodeOptions: false` to disable built-in highlighting when providing your own plugin. A `rehypePlugins` callback can also remove or replace Fumadocs' default highlighter without Highlights being added back.
|
|
365
|
+
|
|
366
|
+
The private package retains its existing Shiki pipeline. The `highlighter` option above is available only in the public package.
|
|
367
|
+
|
|
286
368
|
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.
|
|
287
369
|
|
|
288
370
|
## Page URLs
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import { createSource } from "@vercel/geistdocs/source";
|
|
2
|
+
import docs from "@/.source/search/docs";
|
|
3
|
+
import { config } from "./config";
|
|
4
|
+
|
|
5
|
+
// Search-only metadata and sections. Keep .source/server out of this module.
|
|
6
|
+
export const searchSource = createSource({ docs, config });
|
package/template/next.config.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { join } from "node:path";
|
|
|
3
3
|
import { createGeistdocs } from "@vercel/geistdocs/next";
|
|
4
4
|
import type { NextConfig } from "next";
|
|
5
5
|
|
|
6
|
-
const withGeistdocs = createGeistdocs();
|
|
6
|
+
const withGeistdocs = createGeistdocs({ searchIndex: true });
|
|
7
7
|
|
|
8
8
|
// In this monorepo, compile @vercel/geistdocs from its workspace source so edits
|
|
9
9
|
// to the package hot-reload in the running dev server (no rebuild/restart).
|
package/template/package.json
CHANGED
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
"@streamdown/code": "^1.0.1",
|
|
18
18
|
"@vercel/agent-readability": "^0.7.0",
|
|
19
19
|
"@vercel/analytics": "^1.6.1",
|
|
20
|
-
"@vercel/geistdocs": "2.
|
|
20
|
+
"@vercel/geistdocs": "2.16.0-canary.abbda54",
|
|
21
21
|
"@vercel/speed-insights": "^1.3.1",
|
|
22
22
|
"ai": "^6.0.132",
|
|
23
23
|
"clsx": "^2.1.1",
|