@vercel/geistdocs 2.15.4-canary.2a54b38 → 2.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +3 -3
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/internal/mdx-to-markdown.d.ts.map +1 -1
  5. package/dist/internal/mdx-to-markdown.js +0 -9
  6. package/dist/internal/navbar/mobile-menu.d.ts +3 -3
  7. package/dist/internal/navbar/mobile-menu.d.ts.map +1 -1
  8. package/dist/internal/navbar/mobile-menu.js +3 -3
  9. package/dist/internal/navbar/navbar-logo.d.ts +5 -3
  10. package/dist/internal/navbar/navbar-logo.d.ts.map +1 -1
  11. package/dist/internal/navbar/navbar-logo.js +71 -14
  12. package/dist/internal/page-actions.d.ts +4 -4
  13. package/dist/internal/page-actions.d.ts.map +1 -1
  14. package/dist/internal/page-actions.js +1 -6
  15. package/dist/mdx.d.ts +25 -3
  16. package/dist/mdx.d.ts.map +1 -1
  17. package/dist/mdx.js +61 -8
  18. package/dist/navbar.js +4 -3
  19. package/dist/next.d.ts +1 -11
  20. package/dist/next.d.ts.map +1 -1
  21. package/dist/next.js +2 -82
  22. package/dist/pages/docs.d.ts +98 -5
  23. package/dist/pages/docs.d.ts.map +1 -1
  24. package/dist/pages/docs.js +250 -13
  25. package/dist/source-config.d.ts +1 -10
  26. package/dist/source-config.d.ts.map +1 -1
  27. package/dist/source-config.js +10 -21
  28. package/dist/source.d.ts +17 -6
  29. package/dist/source.d.ts.map +1 -1
  30. package/dist/source.js +75 -2
  31. package/docs/agents.md +1 -1
  32. package/docs/llms.txt +8 -22
  33. package/docs/manifest.json +1 -1
  34. package/docs/pages/configuration.md +7 -21
  35. package/package.json +19 -40
  36. package/rehype-code-highlights.d.ts +1 -1
  37. package/rehype-code-highlights.js +49 -1
  38. package/source-config-public.d.ts +15 -0
  39. package/source-config-public.js +47 -0
  40. package/source-config.js +10 -27
  41. package/template/content/docs/configuration.mdx +7 -21
  42. package/template/package.json +4 -7
  43. package/dist/internal/source-loader.d.ts +0 -28
  44. package/dist/internal/source-loader.d.ts.map +0 -1
  45. package/dist/internal/source-loader.js +0 -77
  46. package/dist/mdx-basic.d.ts +0 -27
  47. package/dist/mdx-basic.d.ts.map +0 -1
  48. package/dist/mdx-basic.js +0 -61
  49. package/dist/navigation.d.ts +0 -11
  50. package/dist/navigation.d.ts.map +0 -1
  51. package/dist/navigation.js +0 -8
  52. package/dist/pages/docs-custom.d.ts +0 -111
  53. package/dist/pages/docs-custom.d.ts.map +0 -1
  54. package/dist/pages/docs-custom.js +0 -250
  55. package/native-mdx/LICENSE-mdxjs-rs +0 -22
  56. package/native-mdx/UPSTREAM.md +0 -16
  57. package/native-mdx/binaries/darwin-arm64.node +0 -0
  58. package/native-mdx/binaries/linux-x64-gnu.node +0 -0
  59. package/native-mdx/data-entry.d.mts +0 -15
  60. package/native-mdx/data-entry.mjs +0 -97
  61. package/native-mdx/data-projection.mjs +0 -205
  62. package/native-mdx/fumadocs-adapter.mjs +0 -36
  63. package/native-mdx/index-emitter.mjs +0 -34
  64. package/native-mdx/loader-data.cjs +0 -36
  65. package/native-mdx/loader-mdx.cjs +0 -9
  66. package/native-mdx/loader-mdx.mjs +0 -419
  67. package/native-mdx/native-binding.cjs +0 -27
  68. package/native-mdx/navigation-entry.d.mts +0 -11
  69. package/native-mdx/navigation-entry.mjs +0 -136
  70. package/native-mdx/navigation-title.mjs +0 -53
  71. package/template/pnpm-workspace.yaml +0 -3
package/dist/source.js CHANGED
@@ -1,6 +1,7 @@
1
+ import { defineI18n } from "fumadocs-core/i18n";
2
+ import { loader, } from "fumadocs-core/source";
1
3
  import { getPublicPath, withBasePath, } from "./config.js";
2
4
  import { createMdxToMarkdown, } from "./internal/mdx-to-markdown.js";
3
- import { createSourceLoader, } from "./internal/source-loader.js";
4
5
  import { stripVersionRoutePrefix, } from "./internal/version-paths.js";
5
6
  const MARKDOWN_LINK_PATTERN = /(\]\()(\/(?!\/)[^)\s]*)/g;
6
7
  const ROOT_ATTRIBUTE_PATTERN = /(\b(?:href|src)=["'])(\/(?!\/)[^"']*)/g;
@@ -56,6 +57,45 @@ const prefixMarkdownLinks = (markdown, basePath) => {
56
57
  ...prefixContentLinks(lines.slice(frontmatterEnd + 1), basePath),
57
58
  ].join("\n");
58
59
  };
60
+ const createSlugsPlugin = (transform) => {
61
+ // Each locale's storage inherits fallback pages from the default locale by
62
+ // reference, so transform every page object once.
63
+ const transformed = new WeakSet();
64
+ return {
65
+ name: "geistdocs:slugs",
66
+ // Runs after Fumadocs assigns the default slugs, so `index` pages and
67
+ // folder groups resolve before the transform sees them.
68
+ enforce: "post",
69
+ transformStorage({ storage }) {
70
+ const pathsByUrl = new Map();
71
+ for (const key of storage.getFiles()) {
72
+ const file = storage.read(key);
73
+ if (file?.format !== "page") {
74
+ continue;
75
+ }
76
+ if (!transformed.has(file)) {
77
+ // Storage keys drop the locale; `file.path` is the content file path.
78
+ file.slugs = transform({ path: file.path, slugs: [...file.slugs] });
79
+ transformed.add(file);
80
+ }
81
+ const url = file.slugs.join("/");
82
+ const existing = pathsByUrl.get(url);
83
+ if (existing) {
84
+ throw new Error(`Geistdocs slugs: ${existing} and ${file.path} both resolve to "/${url}".`);
85
+ }
86
+ pathsByUrl.set(url, file.path);
87
+ }
88
+ },
89
+ };
90
+ };
91
+ const getLanguages = (config) => {
92
+ const defaultLanguage = config.defaultLanguage ?? "en";
93
+ const languages = Object.keys(config.translations ?? {});
94
+ return {
95
+ defaultLanguage,
96
+ languages: Array.from(new Set([defaultLanguage, ...languages])),
97
+ };
98
+ };
59
99
  const YAML_NEEDS_QUOTING = /[:#{}[\]&*!|>'"%@`]/;
60
100
  const ALWAYS_QUOTED_FRONTMATTER = new Set(["badge", "navTitle"]);
61
101
  const formatFrontmatterValue = (value, forceQuotes = false) => {
@@ -90,8 +130,41 @@ const formatFrontmatter = (fields) => {
90
130
  lines.push("---");
91
131
  return lines.join("\n");
92
132
  };
133
+ const pageTreeTransformer = {
134
+ file(node, filePath) {
135
+ if (!filePath) {
136
+ return node;
137
+ }
138
+ const file = this.storage.read(filePath);
139
+ if (file?.format !== "page") {
140
+ return node;
141
+ }
142
+ const { badge, navTitle } = file.data;
143
+ return {
144
+ ...node,
145
+ ...(typeof badge === "string" && badge.length > 0 ? { badge } : {}),
146
+ ...(typeof navTitle === "string" && navTitle.length > 0
147
+ ? { name: navTitle }
148
+ : {}),
149
+ };
150
+ },
151
+ };
93
152
  export const createSource = ({ docs, config, baseUrl = "/docs", id, label, markdown, slugs, }) => {
94
- const source = createSourceLoader({ docs, config, baseUrl, slugs });
153
+ const { defaultLanguage, languages } = getLanguages(config);
154
+ const i18n = defineI18n({
155
+ defaultLanguage,
156
+ languages,
157
+ hideLocale: "default-locale",
158
+ });
159
+ const source = loader({
160
+ i18n,
161
+ baseUrl,
162
+ pageTree: {
163
+ transformers: [pageTreeTransformer],
164
+ },
165
+ plugins: slugs ? [createSlugsPlugin(slugs)] : undefined,
166
+ source: docs.toFumadocsSource(),
167
+ });
95
168
  const getPageImage = (page) => {
96
169
  const segments = [...page.slugs, "image.png"];
97
170
  return {
package/docs/agents.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Docs
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 2.15.4-canary.2a54b38 so agents can understand the installed package without web access.
3
+ These docs are bundled with `@vercel/geistdocs` 2.16.0 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` 2.15.4-canary.2a54b38.
3
+ These docs are bundled with `@vercel/geistdocs` 2.16.0.
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
@@ -1244,7 +1244,7 @@ export const navbarBrand: GeistdocsNavbarBrand = "labs";
1244
1244
 
1245
1245
  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`.
1246
1246
 
1247
- Labs links to [vercel.com/labs](https://vercel.com/labs) and adapts to light and dark themes. Brand selection is independent of `navbarVariant`, which selects the `"oss"` (default) or `"vercel"` layout; either supports both brands. The previous `"standard"` value remains supported as an alias for `"vercel"`. The OSS layout keeps your project's `Logo` and `logoHref` separate from the brand. The Vercel layout shows only the selected brand mark, with no separator, project logo, or OSS products menu.
1247
+ 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.
1248
1248
 
1249
1249
  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).
1250
1250
 
@@ -1424,32 +1424,18 @@ export const docs = defineDocs({
1424
1424
  export default defineGeistdocsSourceConfig();
1425
1425
  ```
1426
1426
 
1427
- ### MDX compiler
1427
+ ### Code highlighter (public package)
1428
1428
 
1429
- `createGeistdocs()` uses the native Rust MDX compiler by default with both Turbopack and webpack. Compatible pages compile natively; custom plugins, Shiki, unsupported content and platforms without a native binary use the JS pipeline automatically. Build output reports fallback reasons.
1430
-
1431
- Select a compiler in `next.config.ts`:
1432
-
1433
- ```ts
1434
- const withGeistdocs = createGeistdocs({ mdxCompiler: "auto" });
1435
- ```
1436
-
1437
- - `"auto"` (default): native when compatible, JS otherwise.
1438
- - `"native"`: fail if a page needs JS fallback; useful for checking native coverage.
1439
- - `"js"`: use the existing JS compiler for every page.
1440
-
1441
- Frontmatter-only requests do not compile page bodies. Native binaries ship with Geistdocs for macOS arm64 and Linux x64 (glibc 2.31+); consumers do not install Rust or a separate compiler package. Unsupported native content currently includes npm fences, Markdown images, includes, explicit code-tab wrappers and math. Actual native compiler errors fail the build instead of silently switching compilers.
1442
-
1443
- ### Code highlighter
1444
-
1445
- For a custom highlighter, pass `highlighter: false` to `defineGeistdocsSourceConfig`; the native compiler will fall back to JS so your plugins run. Passing `mdxOptions.rehypeCodeOptions: false` to the helper also disables built-in highlighting.
1446
-
1447
- Code blocks are tokenized by [Highlights](https://diffs.com/highlights), which uses hand-written WebAssembly lexers, and rendered with the same HTML as Shiki: Geist colors, titles, icons, tabs, and `[!code ...]` notation all work. Languages without a built-in Highlights lexer render as plain text. To use Shiki's TextMate grammars instead, for example for an unsupported language, pass `highlighter: "shiki"`:
1429
+ 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"`:
1448
1430
 
1449
1431
  ```ts title="source.config.ts"
1450
1432
  export default defineGeistdocsSourceConfig({ highlighter: "shiki" });
1451
1433
  ```
1452
1434
 
1435
+ 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.
1436
+
1437
+ The private package retains its existing Shiki pipeline. The `highlighter` option above is available only in the public package.
1438
+
1453
1439
  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.
1454
1440
 
1455
1441
  ## Page URLs
@@ -467,5 +467,5 @@
467
467
  }
468
468
  ],
469
469
  "source": "apps/template/content/docs",
470
- "version": "2.15.4-canary.2a54b38"
470
+ "version": "2.16.0"
471
471
  }
@@ -105,7 +105,7 @@ export const navbarBrand: GeistdocsNavbarBrand = "labs";
105
105
 
106
106
  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`.
107
107
 
108
- Labs links to [vercel.com/labs](https://vercel.com/labs) and adapts to light and dark themes. Brand selection is independent of `navbarVariant`, which selects the `"oss"` (default) or `"vercel"` layout; either supports both brands. The previous `"standard"` value remains supported as an alias for `"vercel"`. The OSS layout keeps your project's `Logo` and `logoHref` separate from the brand. The Vercel layout shows only the selected brand mark, with no separator, project logo, or OSS products menu.
108
+ 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.
109
109
 
110
110
  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).
111
111
 
@@ -285,32 +285,18 @@ export const docs = defineDocs({
285
285
  export default defineGeistdocsSourceConfig();
286
286
  ```
287
287
 
288
- ### MDX compiler
288
+ ### Code highlighter (public package)
289
289
 
290
- `createGeistdocs()` uses the native Rust MDX compiler by default with both Turbopack and webpack. Compatible pages compile natively; custom plugins, Shiki, unsupported content and platforms without a native binary use the JS pipeline automatically. Build output reports fallback reasons.
291
-
292
- Select a compiler in `next.config.ts`:
293
-
294
- ```ts
295
- const withGeistdocs = createGeistdocs({ mdxCompiler: "auto" });
296
- ```
297
-
298
- - `"auto"` (default): native when compatible, JS otherwise.
299
- - `"native"`: fail if a page needs JS fallback; useful for checking native coverage.
300
- - `"js"`: use the existing JS compiler for every page.
301
-
302
- Frontmatter-only requests do not compile page bodies. Native binaries ship with Geistdocs for macOS arm64 and Linux x64 (glibc 2.31+); consumers do not install Rust or a separate compiler package. Unsupported native content currently includes npm fences, Markdown images, includes, explicit code-tab wrappers and math. Actual native compiler errors fail the build instead of silently switching compilers.
303
-
304
- ### Code highlighter
305
-
306
- For a custom highlighter, pass `highlighter: false` to `defineGeistdocsSourceConfig`; the native compiler will fall back to JS so your plugins run. Passing `mdxOptions.rehypeCodeOptions: false` to the helper also disables built-in highlighting.
307
-
308
- Code blocks are tokenized by [Highlights](https://diffs.com/highlights), which uses hand-written WebAssembly lexers, and rendered with the same HTML as Shiki: Geist colors, titles, icons, tabs, and `[!code ...]` notation all work. Languages without a built-in Highlights lexer render as plain text. To use Shiki's TextMate grammars instead, for example for an unsupported language, pass `highlighter: "shiki"`:
290
+ 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"`:
309
291
 
310
292
  ```ts title="source.config.ts"
311
293
  export default defineGeistdocsSourceConfig({ highlighter: "shiki" });
312
294
  ```
313
295
 
296
+ 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.
297
+
298
+ The private package retains its existing Shiki pipeline. The `highlighter` option above is available only in the public package.
299
+
314
300
  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.
315
301
 
316
302
  ## Page URLs
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.4-canary.2a54b38",
4
+ "version": "2.16.0",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -34,13 +34,14 @@
34
34
  "remark-details.d.ts",
35
35
  "remark-details.js",
36
36
  "source-config.js",
37
+ "source-config-public.js",
38
+ "source-config-public.d.ts",
37
39
  "template",
38
40
  "public-foundation.css",
39
41
  "shared-theme.css",
40
42
  "styles.css",
41
43
  "theme.css",
42
- "LICENSE",
43
- "native-mdx"
44
+ "LICENSE"
44
45
  ],
45
46
  "exports": {
46
47
  "./changelog": {
@@ -95,10 +96,6 @@
95
96
  "types": "./dist/source.d.ts",
96
97
  "default": "./dist/source.js"
97
98
  },
98
- "./navigation": {
99
- "types": "./dist/navigation.d.ts",
100
- "default": "./dist/navigation.js"
101
- },
102
99
  "./sidebar": {
103
100
  "types": "./dist/sidebar.d.ts",
104
101
  "default": "./dist/sidebar.js"
@@ -168,8 +165,8 @@
168
165
  "default": "./dist/providers/public/utils.js"
169
166
  },
170
167
  "./source-config": {
171
- "types": "./dist/source-config.d.ts",
172
- "default": "./source-config.js"
168
+ "types": "./source-config-public.d.ts",
169
+ "default": "./source-config-public.js"
173
170
  },
174
171
  "./docs/agents.md": "./docs/agents.md",
175
172
  "./docs/llms.txt": "./docs/llms.txt",
@@ -306,35 +303,13 @@
306
303
  },
307
304
  "./styles.css": "./styles.css",
308
305
  "./theme.css": "./theme.css",
309
- "./package.json": "./package.json",
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
- }
328
- },
329
- "scripts": {
330
- "build": "node ../../scripts/prepare-native-loader.mjs --runtime-only && 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",
331
- "dev": "tsc -p tsconfig.runtime.json --watch --preserveWatchOutput"
306
+ "./package.json": "./package.json"
332
307
  },
333
308
  "dependencies": {
334
309
  "@ai-sdk/react": "^3.0.134",
335
310
  "@clack/prompts": "^0.11.0",
336
- "@modelcontextprotocol/server": "^2.3.0",
337
- "@next/env": "16.4.5",
311
+ "@modelcontextprotocol/server": "^2.0.0",
312
+ "@next/env": "16.3.3",
338
313
  "@orama/tokenizers": "^3.1.16",
339
314
  "@pierre/highlights": "0.5.1",
340
315
  "@shikijs/rehype": "3.19.0",
@@ -353,9 +328,9 @@
353
328
  "fumadocs-mdx": "14.0.4",
354
329
  "fumadocs-ui": "16.2.2",
355
330
  "geist": "1.7.1",
356
- "glob": "^14.0.2",
331
+ "glob": "^11.0.0",
357
332
  "mcp-handler": "2.2.0",
358
- "mermaid": "^11.16.1",
333
+ "mermaid": "^11.12.2",
359
334
  "next-themes": "^0.4.6",
360
335
  "phase": "^0.5.4",
361
336
  "radix-ui": "1.6.4",
@@ -376,10 +351,10 @@
376
351
  "unist-util-visit": "^5.1.0",
377
352
  "use-stick-to-bottom": "^1.1.1",
378
353
  "vaul": "^1.1.2",
379
- "zod": "^4.6.6"
354
+ "zod": "^4.6.5"
380
355
  },
381
356
  "peerDependencies": {
382
- "next": "^16.4.5",
357
+ "next": "^16.3.3",
383
358
  "react": "^19.2.3",
384
359
  "react-dom": "^19.2.3",
385
360
  "tailwindcss": "^4.1.17"
@@ -391,10 +366,14 @@
391
366
  "@types/node": "^24.10.1",
392
367
  "@types/react-dom": "^19.2.3",
393
368
  "mdast-util-mdx-jsx": "^3.2.0",
394
- "next": "16.4.5",
369
+ "next": "16.3.3",
395
370
  "react": "^19.2.3",
396
371
  "react-dom": "^19.2.3",
397
372
  "tsup": "^8.5.1",
398
373
  "typescript": "^5.9.3"
374
+ },
375
+ "scripts": {
376
+ "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",
377
+ "dev": "tsc -p tsconfig.runtime.json --watch --preserveWatchOutput"
399
378
  }
400
- }
379
+ }
@@ -5,7 +5,7 @@ import type { Root } from "hast";
5
5
  export declare const geistHighlightsTheme: Record<string, unknown>;
6
6
 
7
7
  /**
8
- * Experimental drop-in for Fumadocs' `rehypeCode` that tokenizes with
8
+ * Drop-in for Fumadocs' `rehypeCode` that tokenizes with
9
9
  * @pierre/highlights while keeping Shiki's HAST output and transformers.
10
10
  */
11
11
  export declare const rehypeCodeHighlights: (
@@ -7,7 +7,7 @@ import {
7
7
  } from "fumadocs-core/mdx-plugins";
8
8
  import { tokensToHast, transformerDecorations } from "shiki/core";
9
9
 
10
- // Experimental: highlights code blocks with @pierre/highlights (hand-written
10
+ // Highlights code blocks with @pierre/highlights (hand-written
11
11
  // Wasm lexers) instead of Shiki's TextMate grammars, while keeping Shiki's
12
12
  // HAST output and transformer pipeline so Fumadocs' code block features
13
13
  // (titles, icons, tabs, line notation, diffs, focus) keep working.
@@ -116,6 +116,53 @@ const getTransformers = (options) => [
116
116
  ];
117
117
 
118
118
  const UNSTYLED = "var(--shiki-foreground)";
119
+ const COMMENT = "var(--shiki-token-comment)";
120
+ const TRAILING_SPACE = /[\t ]+$/;
121
+
122
+ const joinCommentWhitespace = (line) => {
123
+ for (let index = 1; index < line.length; index++) {
124
+ const token = line[index];
125
+ if (token.htmlStyle?.color !== COMMENT) {
126
+ continue;
127
+ }
128
+ // Shiki groups JSX indentation with the opening brace. Its annotation
129
+ // transformer recognizes a standalone JSX comment by those three tokens.
130
+ const opening = index - 1;
131
+ if (
132
+ token.content.trimStart().startsWith("/*") &&
133
+ line[opening].content.trim() === "{" &&
134
+ line[index + 1]?.content.trim() === "}" &&
135
+ line.slice(0, opening).every((part) => part.content.trim() === "")
136
+ ) {
137
+ const indentation = line
138
+ .slice(0, opening)
139
+ .map((part) => part.content)
140
+ .join("");
141
+ line[opening].content = indentation + line[opening].content;
142
+ line[opening].offset -= indentation.length;
143
+ line.splice(0, opening);
144
+ index -= opening;
145
+ }
146
+ // Shiki includes the separator before a comment in its comment token.
147
+ // Match that boundary so notation removal also removes the separator,
148
+ // without trimming authored whitespace from unrelated code lines.
149
+ while (index > 0) {
150
+ const previous = line[index - 1];
151
+ const whitespace = previous.content.match(TRAILING_SPACE)?.[0];
152
+ if (!whitespace) {
153
+ break;
154
+ }
155
+ previous.content = previous.content.slice(0, -whitespace.length);
156
+ token.content = whitespace + token.content;
157
+ token.offset -= whitespace.length;
158
+ if (previous.content) {
159
+ break;
160
+ }
161
+ line.splice(index - 1, 1);
162
+ index--;
163
+ }
164
+ }
165
+ };
119
166
 
120
167
  const tokenize = (code, options) => {
121
168
  const result = codeToTokens(code, {
@@ -127,6 +174,7 @@ const tokenize = (code, options) => {
127
174
  // Highlights colors unstyled runs with `var(--shiki-foreground)`; Shiki uses
128
175
  // the theme foreground, which Geist defines as `--shiki-color-text`.
129
176
  for (const line of result.tokens) {
177
+ joinCommentWhitespace(line);
130
178
  for (const token of line) {
131
179
  if (token.htmlStyle?.color === UNSTYLED) {
132
180
  token.htmlStyle = { ...token.htmlStyle, color: result.fg };
@@ -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
@@ -15,7 +15,6 @@ import {
15
15
  } from "fumadocs-mdx/config";
16
16
  import lastModified from "fumadocs-mdx/plugins/last-modified";
17
17
  import { z } from "zod";
18
- import { rehypeCodeHighlights } from "./rehype-code-highlights.js";
19
18
  import { rehypeTaskListLabels } from "./rehype-task-list-labels.js";
20
19
  import { remarkDetails } from "./remark-details.js";
21
20
 
@@ -277,18 +276,11 @@ export const resolveGeistdocsRemarkPlugins = (
277
276
  // Mirrors src/source-config.ts. Geistdocs rehype plugins run after the
278
277
  // consumer's: an array is handed to Fumadocs, which places it among its
279
278
  // defaults; a function receives those defaults and returns the final list.
280
- export const resolveGeistdocsRehypePlugins = (
281
- consumerPlugins,
282
- leadingPlugins = []
283
- ) => {
279
+ export const resolveGeistdocsRehypePlugins = (consumerPlugins) => {
284
280
  if (typeof consumerPlugins === "function") {
285
- return (defaults) => [
286
- ...leadingPlugins,
287
- ...consumerPlugins(defaults),
288
- rehypeTaskListLabels,
289
- ];
281
+ return (defaults) => [...consumerPlugins(defaults), rehypeTaskListLabels];
290
282
  }
291
- return [...leadingPlugins, ...(consumerPlugins ?? []), rehypeTaskListLabels];
283
+ return [...(consumerPlugins ?? []), rehypeTaskListLabels];
292
284
  };
293
285
 
294
286
  export const defineGeistdocsSourceConfig = (config = {}) => {
@@ -296,30 +288,21 @@ export const defineGeistdocsSourceConfig = (config = {}) => {
296
288
  ? config.mdxOptions.remarkPlugins
297
289
  : [];
298
290
  const existingPlugins = Array.isArray(config.plugins) ? config.plugins : [];
299
- const { highlighter = "highlights", ...fumadocsConfig } = config;
300
- const rehypeCodeOptions = {
301
- ...config.mdxOptions?.rehypeCodeOptions,
302
- themes: { light: geistShikiTheme },
303
- defaultColor: "light",
304
- };
305
- // `highlights` swaps Shiki's tokenizer for @pierre/highlights; `shiki`
306
- // keeps Fumadocs' rehypeCode.
307
- const highlightingDisabled =
308
- highlighter === false || config.mdxOptions?.rehypeCodeOptions === false;
309
- const useHighlights = highlighter === "highlights" && !highlightingDisabled;
310
291
 
311
292
  return defineFumadocsConfig({
312
- ...fumadocsConfig,
293
+ ...config,
313
294
  mdxOptions: {
314
295
  ...config.mdxOptions,
315
296
  remarkPlugins: (defaults) =>
316
297
  resolveGeistdocsRemarkPlugins(defaults, existingRemarkPlugins),
317
298
  rehypePlugins: resolveGeistdocsRehypePlugins(
318
- config.mdxOptions?.rehypePlugins,
319
- useHighlights ? [[rehypeCodeHighlights, rehypeCodeOptions]] : []
299
+ config.mdxOptions?.rehypePlugins
320
300
  ),
321
- rehypeCodeOptions:
322
- useHighlights || highlightingDisabled ? false : rehypeCodeOptions,
301
+ rehypeCodeOptions: {
302
+ ...config.mdxOptions?.rehypeCodeOptions,
303
+ themes: { light: geistShikiTheme },
304
+ defaultColor: "light",
305
+ },
323
306
  },
324
307
  plugins: [
325
308
  lastModified({ versionControl: getLastModified }),
@@ -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. Brand selection is independent of `navbarVariant`, which selects the `"oss"` (default) or `"vercel"` layout; either supports both brands. The previous `"standard"` value remains supported as an alias for `"vercel"`. The OSS layout keeps your project's `Logo` and `logoHref` separate from the brand. The Vercel layout shows only the selected brand mark, with no separator, project logo, or OSS products menu.
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,32 +283,18 @@ export const docs = defineDocs({
283
283
  export default defineGeistdocsSourceConfig();
284
284
  ```
285
285
 
286
- ### MDX compiler
286
+ ### Code highlighter (public package)
287
287
 
288
- `createGeistdocs()` uses the native Rust MDX compiler by default with both Turbopack and webpack. Compatible pages compile natively; custom plugins, Shiki, unsupported content and platforms without a native binary use the JS pipeline automatically. Build output reports fallback reasons.
289
-
290
- Select a compiler in `next.config.ts`:
291
-
292
- ```ts
293
- const withGeistdocs = createGeistdocs({ mdxCompiler: "auto" });
294
- ```
295
-
296
- - `"auto"` (default): native when compatible, JS otherwise.
297
- - `"native"`: fail if a page needs JS fallback; useful for checking native coverage.
298
- - `"js"`: use the existing JS compiler for every page.
299
-
300
- Frontmatter-only requests do not compile page bodies. Native binaries ship with Geistdocs for macOS arm64 and Linux x64 (glibc 2.31+); consumers do not install Rust or a separate compiler package. Unsupported native content currently includes npm fences, Markdown images, includes, explicit code-tab wrappers and math. Actual native compiler errors fail the build instead of silently switching compilers.
301
-
302
- ### Code highlighter
303
-
304
- For a custom highlighter, pass `highlighter: false` to `defineGeistdocsSourceConfig`; the native compiler will fall back to JS so your plugins run. Passing `mdxOptions.rehypeCodeOptions: false` to the helper also disables built-in highlighting.
305
-
306
- Code blocks are tokenized by [Highlights](https://diffs.com/highlights), which uses hand-written WebAssembly lexers, and rendered with the same HTML as Shiki: Geist colors, titles, icons, tabs, and `[!code ...]` notation all work. Languages without a built-in Highlights lexer render as plain text. To use Shiki's TextMate grammars instead, for example for an unsupported language, pass `highlighter: "shiki"`:
288
+ 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"`:
307
289
 
308
290
  ```ts title="source.config.ts"
309
291
  export default defineGeistdocsSourceConfig({ highlighter: "shiki" });
310
292
  ```
311
293
 
294
+ 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.
295
+
296
+ The private package retains its existing Shiki pipeline. The `highlighter` option above is available only in the public package.
297
+
312
298
  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.
313
299
 
314
300
  ## Page URLs