@vercel/geistdocs 2.15.3-canary.633944d → 2.15.3-canary.7d55dcf

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/internal/mdx-to-markdown.d.ts.map +1 -1
  3. package/dist/internal/mdx-to-markdown.js +9 -0
  4. package/dist/internal/page-actions.d.ts +4 -4
  5. package/dist/internal/page-actions.d.ts.map +1 -1
  6. package/dist/internal/page-actions.js +6 -1
  7. package/dist/internal/source-loader.d.ts +28 -0
  8. package/dist/internal/source-loader.d.ts.map +1 -0
  9. package/dist/internal/source-loader.js +77 -0
  10. package/dist/mdx-basic.d.ts +27 -0
  11. package/dist/mdx-basic.d.ts.map +1 -0
  12. package/dist/mdx-basic.js +61 -0
  13. package/dist/mdx.d.ts +3 -25
  14. package/dist/mdx.d.ts.map +1 -1
  15. package/dist/mdx.js +8 -61
  16. package/dist/navigation.d.ts +11 -0
  17. package/dist/navigation.d.ts.map +1 -0
  18. package/dist/navigation.js +8 -0
  19. package/dist/pages/docs-custom.d.ts +111 -0
  20. package/dist/pages/docs-custom.d.ts.map +1 -0
  21. package/dist/pages/docs-custom.js +250 -0
  22. package/dist/pages/docs.d.ts +5 -98
  23. package/dist/pages/docs.d.ts.map +1 -1
  24. package/dist/pages/docs.js +13 -250
  25. package/dist/source.d.ts +6 -17
  26. package/dist/source.d.ts.map +1 -1
  27. package/dist/source.js +2 -75
  28. package/docs/agents.md +1 -1
  29. package/docs/llms.txt +1 -1
  30. package/docs/manifest.json +1 -1
  31. package/native-mdx/data-entry.d.mts +15 -0
  32. package/native-mdx/data-entry.mjs +97 -0
  33. package/native-mdx/data-projection.mjs +205 -0
  34. package/native-mdx/index-emitter.mjs +34 -0
  35. package/native-mdx/loader-data.cjs +36 -0
  36. package/native-mdx/loader-mdx.mjs +50 -4
  37. package/native-mdx/navigation-entry.d.mts +11 -0
  38. package/native-mdx/navigation-entry.mjs +136 -0
  39. package/native-mdx/navigation-title.mjs +53 -0
  40. package/package.json +23 -2
  41. package/template/package.json +1 -1
@@ -3,6 +3,8 @@
3
3
  // frontmatter validation, and doc plugins stay in JS (they're user code);
4
4
  // parsing, transforms, highlighting, and codegen run natively. Files that
5
5
  // use something the native pipeline doesn't cover go to fumadocs-mdx.
6
+ import { createHash } from "node:crypto";
7
+ import { readFile } from "node:fs/promises";
6
8
  import { createRequire } from "node:module";
7
9
  import path from "node:path";
8
10
  import { pathToFileURL } from "node:url";
@@ -24,7 +26,8 @@ const native = require(
24
26
 
25
27
  let configLoader;
26
28
  let jsLoader;
27
- const compatibility = new Map();
29
+ let compiledConfigIdentity;
30
+ const compatibility = new WeakMap();
28
31
 
29
32
  // The plugin list the native pipeline implements: Geistdocs' defaults with
30
33
  // Highlights (`defineGeistdocsSourceConfig()`), in fumadocs-mdx's order.
@@ -71,8 +74,13 @@ const samePlugins = (actual, expected) =>
71
74
 
72
75
  /** Why a collection's MDX options need the JS pipeline, if they do. */
73
76
  async function incompatibility(config, collection) {
77
+ // Collection names survive config reloads; compatibility decisions must not.
78
+ if (!compatibility.has(config)) {
79
+ compatibility.set(config, new Map());
80
+ }
81
+ const reasons = compatibility.get(config);
74
82
  const key = collection?.name ?? "global";
75
- if (!compatibility.has(key)) {
83
+ if (!reasons.has(key)) {
76
84
  const options = await config.getMDXOptions(collection, "bundler");
77
85
  let reason = null;
78
86
  const extraKeys = Object.keys(options).filter(
@@ -85,9 +93,9 @@ async function incompatibility(config, collection) {
85
93
  } else if (!samePlugins(options.rehypePlugins ?? [], NATIVE_REHYPE)) {
86
94
  reason = "custom rehype plugins or Shiki";
87
95
  }
88
- compatibility.set(key, reason);
96
+ reasons.set(key, reason);
89
97
  }
90
- return compatibility.get(key);
98
+ return reasons.get(key);
91
99
  }
92
100
 
93
101
  /** The doc collection behind a `doc` or `docs` collection. */
@@ -124,6 +132,30 @@ const literal = (value) => {
124
132
  return JSON.stringify(value);
125
133
  };
126
134
 
135
+ async function fillNavigationTitle(matter, config, docCollection, filePath) {
136
+ if (matter.data.title === "") {
137
+ throw new Error(
138
+ "Navigation requires a nonempty frontmatter title; omit it to use heading fallback with a compatible schema"
139
+ );
140
+ }
141
+ if (matter.data.title != null) {
142
+ return;
143
+ }
144
+ if (await incompatibility(config, docCollection)) {
145
+ throw new Error(
146
+ "Navigation requires an explicit frontmatter title when using custom MDX plugins or options"
147
+ );
148
+ }
149
+ const { navigationTitle } = await import("./navigation-title.mjs");
150
+ const title = await navigationTitle(
151
+ matter.content,
152
+ filePath.endsWith(".mdx") ? "mdx" : "md"
153
+ );
154
+ if (title !== undefined) {
155
+ matter.data.title = title;
156
+ }
157
+ }
158
+
127
159
  export async function load({
128
160
  source,
129
161
  filePath,
@@ -132,6 +164,17 @@ export async function load({
132
164
  compiler,
133
165
  options,
134
166
  }) {
167
+ if (development) {
168
+ // Imported settings can change the bundled config without changing the
169
+ // source config's mtime, which is all Fumadocs checks for reloads.
170
+ const compiled = await readFile(options.absoluteCompiledConfigPath);
171
+ const identity = createHash("sha256").update(compiled).digest("hex");
172
+ if (identity !== compiledConfigIdentity) {
173
+ compiledConfigIdentity = identity;
174
+ configLoader = undefined;
175
+ jsLoader = undefined;
176
+ }
177
+ }
135
178
  configLoader ??= createStandaloneConfigLoader({
136
179
  core: getCore(options),
137
180
  buildConfig: false,
@@ -151,6 +194,9 @@ export async function load({
151
194
  );
152
195
  }
153
196
  if (query.only === "frontmatter") {
197
+ if (query["geistdocs-navigation"] === "1") {
198
+ await fillNavigationTitle(matter, config, docCollection, filePath);
199
+ }
154
200
  return `export const frontmatter = ${JSON.stringify(matter.data)}`;
155
201
  }
156
202
 
@@ -0,0 +1,11 @@
1
+ import type { Plugin } from "fumadocs-mdx";
2
+ import type * as TypeScript from "typescript";
3
+ type Parser = typeof TypeScript;
4
+ /** Opt-in metadata-only navigation.ts, for synchronous collections and the native canary loader. */
5
+ export declare function navigationEntryPlugin(
6
+ parser: Parser | (() => Parser | Promise<Parser>)
7
+ ): Plugin;
8
+ export declare function createNavigationEntry(
9
+ serverCode: string,
10
+ parser: Parser
11
+ ): { code: string; imports: number };
@@ -0,0 +1,136 @@
1
+ import { extendIndexEmitter } from "./index-emitter.mjs";
2
+
3
+ const MDX_EXTENSION = /\.mdx?$/;
4
+ const META_EXTENSION = /\.json$/;
5
+
6
+ /** Add navigation.ts to Fumadocs' existing discovery/watch lifecycle. */
7
+ export function navigationEntryPlugin(typeScriptOrLoader) {
8
+ let parserPromise;
9
+ const getParser = () =>
10
+ (parserPromise ??= Promise.resolve()
11
+ .then(() =>
12
+ typeof typeScriptOrLoader === "function"
13
+ ? typeScriptOrLoader()
14
+ : typeScriptOrLoader
15
+ )
16
+ .then((module) => module.default ?? module));
17
+ return {
18
+ name: "geistdocs-navigation-entry",
19
+ config() {
20
+ const collections = this.core.getConfig?.().collectionList ?? [];
21
+ for (const collection of collections) {
22
+ const doc = collection.type === "docs" ? collection.docs : collection;
23
+ if (doc.dynamic || doc.async) {
24
+ throw new Error(
25
+ "Navigation entries require synchronous collections; disable docs.async and docs.dynamic"
26
+ );
27
+ }
28
+ }
29
+ extendIndexEmitter(
30
+ this,
31
+ "geistdocs-navigation-entry",
32
+ async (entries) => {
33
+ const server = entries.find((entry) => entry.path === "server.ts");
34
+ if (
35
+ !server ||
36
+ entries.some((entry) => entry.path === "navigation.ts")
37
+ ) {
38
+ throw new Error(
39
+ "Content entries require server.ts and an unused navigation.ts output"
40
+ );
41
+ }
42
+ return [
43
+ ...entries,
44
+ {
45
+ path: "navigation.ts",
46
+ content: createNavigationEntry(server.content, await getParser())
47
+ .code,
48
+ },
49
+ ];
50
+ }
51
+ );
52
+ },
53
+ };
54
+ }
55
+
56
+ /** Metadata queries only: no renderable MDX imports, including dynamic ones. */
57
+ export function createNavigationEntry(serverCode, ts) {
58
+ const file = ts.createSourceFile(
59
+ "server.ts",
60
+ serverCode,
61
+ ts.ScriptTarget.Latest,
62
+ true,
63
+ ts.ScriptKind.TS
64
+ );
65
+ if (file.parseDiagnostics.length) {
66
+ throw new Error("Cannot parse generated server entry");
67
+ }
68
+ const edits = [];
69
+ function inspect(node) {
70
+ if (
71
+ ts.isMetaProperty(node) &&
72
+ node.keywordToken === ts.SyntaxKind.ImportKeyword
73
+ ) {
74
+ throw new Error("Navigation entries do not support Vite glob entries");
75
+ }
76
+ if (
77
+ ts.isCallExpression(node) &&
78
+ (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
79
+ (ts.isPropertyAccessExpression(node.expression) &&
80
+ ["docsLazy", "docLazy"].includes(node.expression.name.text)))
81
+ ) {
82
+ throw new Error(
83
+ "Navigation entries currently require synchronous Fumadocs collections; leave docs.async disabled"
84
+ );
85
+ }
86
+ ts.forEachChild(node, inspect);
87
+ }
88
+ inspect(file);
89
+ for (const statement of file.statements) {
90
+ if (
91
+ !(
92
+ ts.isImportDeclaration(statement) &&
93
+ ts.isStringLiteral(statement.moduleSpecifier)
94
+ )
95
+ ) {
96
+ continue;
97
+ }
98
+ const specifier = statement.moduleSpecifier;
99
+ const separator = specifier.text.indexOf("?");
100
+ const pathname =
101
+ separator < 0 ? specifier.text : specifier.text.slice(0, separator);
102
+ if (!MDX_EXTENSION.test(pathname)) {
103
+ if (
104
+ !(
105
+ statement.importClause?.isTypeOnly ||
106
+ META_EXTENSION.test(pathname) ||
107
+ pathname === "fumadocs-mdx/runtime/server"
108
+ )
109
+ ) {
110
+ throw new Error(`Unsupported navigation runtime import: ${pathname}`);
111
+ }
112
+ continue;
113
+ }
114
+ const query = new URLSearchParams(
115
+ separator < 0 ? "" : specifier.text.slice(separator + 1)
116
+ );
117
+ if (!query.has("collection")) {
118
+ throw new Error(
119
+ "Navigation MDX imports must identify a Fumadocs collection"
120
+ );
121
+ }
122
+ query.delete("geistdocs-data");
123
+ query.set("only", "frontmatter");
124
+ query.set("geistdocs-navigation", "1");
125
+ edits.push({
126
+ start: specifier.getStart(file),
127
+ end: specifier.end,
128
+ value: JSON.stringify(`${pathname}?${query}`),
129
+ });
130
+ }
131
+ let code = serverCode;
132
+ for (const edit of edits.reverse()) {
133
+ code = code.slice(0, edit.start) + edit.value + code.slice(edit.end);
134
+ }
135
+ return { code, imports: edits.length };
136
+ }
@@ -0,0 +1,53 @@
1
+ let parserPromise;
2
+
3
+ /** Parse only when frontmatter omits a title. Never compile or evaluate MDX. */
4
+ export async function navigationTitle(content, format = "mdx") {
5
+ parserPromise ??= Promise.all([
6
+ import("unified"),
7
+ import("remark-parse"),
8
+ import("remark-mdx"),
9
+ import("remark-gfm"),
10
+ import("fumadocs-core/mdx-plugins/remark-heading"),
11
+ import("fumadocs-core/mdx-plugins/remark-steps"),
12
+ ]);
13
+ const [
14
+ { unified },
15
+ { default: parse },
16
+ { default: mdx },
17
+ { default: gfm },
18
+ { remarkHeading },
19
+ { remarkSteps },
20
+ ] = await parserPromise;
21
+ let parser = unified().use(parse).use(gfm);
22
+ if (format === "mdx") {
23
+ parser = parser.use(mdx);
24
+ }
25
+ parser = parser.use(remarkSteps).use(remarkHeading, { generateToc: false });
26
+ const parsed = parser.parse(content);
27
+ const checkIncludes = (node) => {
28
+ if (node.name === "include") {
29
+ throw new Error(
30
+ "Navigation requires an explicit frontmatter title for pages using include"
31
+ );
32
+ }
33
+ for (const child of node.children ?? []) {
34
+ checkIncludes(child);
35
+ }
36
+ };
37
+ checkIncludes(parsed);
38
+ const tree = await parser.run(parsed);
39
+ const flatten = (node) =>
40
+ node.children ? node.children.map(flatten).join("") : (node.value ?? "");
41
+ const find = (node) => {
42
+ if (node.type === "heading" && node.depth === 1) {
43
+ return flatten(node);
44
+ }
45
+ for (const child of node.children ?? []) {
46
+ const value = find(child);
47
+ if (value !== undefined) {
48
+ return value;
49
+ }
50
+ }
51
+ };
52
+ return find(tree);
53
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@vercel/geistdocs",
3
3
  "description": "Runtime and CLI for Geistdocs projects.",
4
- "version": "2.15.3-canary.633944d",
4
+ "version": "2.15.3-canary.7d55dcf",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -95,6 +95,10 @@
95
95
  "types": "./dist/source.d.ts",
96
96
  "default": "./dist/source.js"
97
97
  },
98
+ "./navigation": {
99
+ "types": "./dist/navigation.d.ts",
100
+ "default": "./dist/navigation.js"
101
+ },
98
102
  "./sidebar": {
99
103
  "types": "./dist/sidebar.d.ts",
100
104
  "default": "./dist/sidebar.js"
@@ -303,7 +307,24 @@
303
307
  "./styles.css": "./styles.css",
304
308
  "./theme.css": "./theme.css",
305
309
  "./package.json": "./package.json",
306
- "./native-mdx": "./native-mdx/loader-mdx.cjs"
310
+ "./pages/docs/custom": {
311
+ "types": "./dist/pages/docs-custom.d.ts",
312
+ "default": "./dist/pages/docs-custom.js"
313
+ },
314
+ "./mdx/basic": {
315
+ "types": "./dist/mdx-basic.d.ts",
316
+ "default": "./dist/mdx-basic.js"
317
+ },
318
+ "./native-mdx": "./native-mdx/loader-mdx.cjs",
319
+ "./native-mdx/data-loader": "./native-mdx/loader-data.cjs",
320
+ "./native-mdx/data-entry": {
321
+ "types": "./native-mdx/data-entry.d.mts",
322
+ "import": "./native-mdx/data-entry.mjs"
323
+ },
324
+ "./native-mdx/navigation-entry": {
325
+ "types": "./native-mdx/navigation-entry.d.mts",
326
+ "import": "./native-mdx/navigation-entry.mjs"
327
+ }
307
328
  },
308
329
  "scripts": {
309
330
  "build": "rm -rf dist docs template && node ./scripts/bundle-template.mjs && node ./scripts/bundle-docs.mjs && tsc -p tsconfig.runtime.json && tsup --config tsup.config.cli.ts",
@@ -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.15.3-canary.633944d",
20
+ "@vercel/geistdocs": "2.15.3-canary.7d55dcf",
21
21
  "@vercel/speed-insights": "^1.3.1",
22
22
  "ai": "^6.0.132",
23
23
  "clsx": "^2.1.1",