@vercel/geistdocs 2.16.0-canary.abbda54 → 3.0.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.
- package/dist/cli/index.js +1 -1
- package/dist/config.d.ts +12 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/internal/lazy-mdx-components.d.ts +0 -2
- package/dist/internal/lazy-mdx-components.d.ts.map +1 -1
- package/dist/internal/lazy-mdx-components.js +0 -1
- package/dist/internal/mermaid-source.d.ts +5 -0
- package/dist/internal/mermaid-source.d.ts.map +1 -0
- package/dist/internal/mermaid-source.js +5 -0
- package/dist/internal/page-action-options.d.ts +9 -4
- package/dist/internal/page-action-options.d.ts.map +1 -1
- package/dist/internal/page-action-options.js +19 -12
- package/dist/internal/page-actions-client.d.ts.map +1 -1
- package/dist/internal/page-actions-client.js +19 -112
- package/dist/internal/page-actions-gate.d.ts +6 -0
- package/dist/internal/page-actions-gate.d.ts.map +1 -1
- package/dist/internal/page-actions-gate.js +11 -9
- package/dist/internal/page-actions-menu-client.d.ts +8 -0
- package/dist/internal/page-actions-menu-client.d.ts.map +1 -0
- package/dist/internal/page-actions-menu-client.js +105 -0
- package/dist/internal/page-markdown.d.ts +3 -0
- package/dist/internal/page-markdown.d.ts.map +1 -0
- package/dist/internal/page-markdown.js +45 -0
- package/dist/internal/toc-actions-client.d.ts +3 -1
- package/dist/internal/toc-actions-client.d.ts.map +1 -1
- package/dist/internal/toc-actions-client.js +7 -9
- package/dist/mdx.js +3 -2
- package/dist/next.d.ts +2 -15
- package/dist/next.d.ts.map +1 -1
- package/dist/next.js +5 -27
- package/dist/pages/docs.d.ts +6 -1
- package/dist/pages/docs.d.ts.map +1 -1
- package/dist/pages/docs.js +11 -6
- package/dist/routes/search.d.ts +1 -8
- package/dist/routes/search.d.ts.map +1 -1
- package/dist/routes/search.js +82 -120
- package/dist/source-config.d.ts +0 -2
- package/dist/source-config.d.ts.map +1 -1
- package/dist/source-config.js +0 -2
- package/docs/agents.md +2 -3
- package/docs/llms.txt +31 -250
- package/docs/manifest.json +2 -11
- package/docs/pages/changelog.md +1 -1
- package/docs/pages/components/index.md +0 -1
- package/docs/pages/configuration.md +24 -73
- package/docs/pages/edit-on-github.md +1 -1
- package/docs/pages/index.md +0 -29
- package/docs/pages/md.md +1 -1
- package/docs/pages/migration.md +1 -1
- package/docs/pages/syntax.md +1 -107
- package/docs/sitemap.md +1 -2
- package/package.json +14 -14
- package/source-config.js +0 -2
- package/template/AGENTS.md +0 -4
- package/template/app/[lang]/docs/[[...slug]]/page.tsx +1 -0
- package/template/app/api/search/route.ts +2 -7
- package/template/content/docs/changelog.mdx +1 -1
- package/template/content/docs/components/index.mdx +0 -1
- package/template/content/docs/components/meta.json +0 -1
- package/template/content/docs/configuration.mdx +24 -73
- package/template/content/docs/edit-on-github.mdx +1 -1
- package/template/content/docs/index.mdx +0 -28
- package/template/content/docs/md.mdx +1 -1
- package/template/content/docs/migration.mdx +1 -1
- package/template/content/docs/syntax.cn.mdx +1 -107
- package/template/content/docs/syntax.mdx +1 -107
- package/template/next.config.ts +1 -1
- package/template/package.json +1 -2
- package/template/source.config.ts +1 -1
- package/docs/pages/components/mermaid.md +0 -29
- package/search-index.d.ts +0 -14
- package/search-index.js +0 -447
- package/template/content/docs/components/mermaid.mdx +0 -25
- package/template/lib/geistdocs/search-source.ts +0 -6
package/docs/pages/syntax.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
title: MDX Components
|
|
3
3
|
description: Author MDX content with supported components, Markdown syntax, and formatting options
|
|
4
4
|
type: reference
|
|
5
|
-
summary: MDX component and authoring reference covering tabs, text formatting, code blocks, line highlighting
|
|
5
|
+
summary: MDX component and authoring reference covering tabs, text formatting, code blocks, and line highlighting.
|
|
6
6
|
url: /docs/syntax
|
|
7
7
|
source: apps/template/content/docs/syntax.mdx
|
|
8
8
|
prerequisites:
|
|
@@ -712,109 +712,3 @@ const numbers = [1, 2, 3, 4, 5];
|
|
|
712
712
|
const sum = numbers.reduce((a, b) => a + b, 0); // [!code focus]
|
|
713
713
|
console.log(sum);
|
|
714
714
|
```
|
|
715
|
-
|
|
716
|
-
## Mermaid Diagrams
|
|
717
|
-
|
|
718
|
-
Create diagrams and flowcharts using Mermaid syntax.
|
|
719
|
-
|
|
720
|
-
### Flowcharts
|
|
721
|
-
|
|
722
|
-
````md
|
|
723
|
-
```mermaid
|
|
724
|
-
graph TD;
|
|
725
|
-
A[Start] --> B{Is it working?};
|
|
726
|
-
B -->|Yes| C[Great!];
|
|
727
|
-
B -->|No| D[Debug];
|
|
728
|
-
D --> B;
|
|
729
|
-
```
|
|
730
|
-
````
|
|
731
|
-
|
|
732
|
-
This renders as:
|
|
733
|
-
|
|
734
|
-
```mermaid
|
|
735
|
-
graph TD;
|
|
736
|
-
A[Start] --> B{Is it working?};
|
|
737
|
-
B -->|Yes| C[Great!];
|
|
738
|
-
B -->|No| D[Debug];
|
|
739
|
-
D --> B;
|
|
740
|
-
```
|
|
741
|
-
|
|
742
|
-
### Sequence Diagrams
|
|
743
|
-
|
|
744
|
-
````md
|
|
745
|
-
```mermaid
|
|
746
|
-
sequenceDiagram
|
|
747
|
-
participant User
|
|
748
|
-
participant API
|
|
749
|
-
participant Database
|
|
750
|
-
User->>API: Request data
|
|
751
|
-
API->>Database: Query
|
|
752
|
-
Database-->>API: Results
|
|
753
|
-
API-->>User: Response
|
|
754
|
-
```
|
|
755
|
-
````
|
|
756
|
-
|
|
757
|
-
This renders as:
|
|
758
|
-
|
|
759
|
-
```mermaid
|
|
760
|
-
sequenceDiagram
|
|
761
|
-
participant User
|
|
762
|
-
participant API
|
|
763
|
-
participant Database
|
|
764
|
-
User->>API: Request data
|
|
765
|
-
API->>Database: Query
|
|
766
|
-
Database-->>API: Results
|
|
767
|
-
API-->>User: Response
|
|
768
|
-
```
|
|
769
|
-
|
|
770
|
-
### Architecture Diagrams
|
|
771
|
-
|
|
772
|
-
````md
|
|
773
|
-
```mermaid
|
|
774
|
-
graph TD;
|
|
775
|
-
subgraph Frontend
|
|
776
|
-
A[Web App]
|
|
777
|
-
B[Mobile App]
|
|
778
|
-
end
|
|
779
|
-
subgraph Backend
|
|
780
|
-
C[API Gateway]
|
|
781
|
-
D[Auth Service]
|
|
782
|
-
E[Data Service]
|
|
783
|
-
end
|
|
784
|
-
subgraph Storage
|
|
785
|
-
F[(Database)]
|
|
786
|
-
G[(Cache)]
|
|
787
|
-
end
|
|
788
|
-
A --> C
|
|
789
|
-
B --> C
|
|
790
|
-
C --> D
|
|
791
|
-
C --> E
|
|
792
|
-
E --> F
|
|
793
|
-
E --> G
|
|
794
|
-
```
|
|
795
|
-
````
|
|
796
|
-
|
|
797
|
-
This renders as:
|
|
798
|
-
|
|
799
|
-
```mermaid
|
|
800
|
-
graph TD;
|
|
801
|
-
subgraph Frontend
|
|
802
|
-
A[Web App]
|
|
803
|
-
B[Mobile App]
|
|
804
|
-
end
|
|
805
|
-
subgraph Backend
|
|
806
|
-
C[API Gateway]
|
|
807
|
-
D[Auth Service]
|
|
808
|
-
E[Data Service]
|
|
809
|
-
end
|
|
810
|
-
subgraph Storage
|
|
811
|
-
F[(Database)]
|
|
812
|
-
G[(Cache)]
|
|
813
|
-
end
|
|
814
|
-
A --> C
|
|
815
|
-
B --> C
|
|
816
|
-
C --> D
|
|
817
|
-
C --> E
|
|
818
|
-
E --> F
|
|
819
|
-
E --> G
|
|
820
|
-
```
|
package/docs/sitemap.md
CHANGED
|
@@ -10,7 +10,7 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
|
|
|
10
10
|
- [Migrate to Geistdocs](pages/migration.md) | URL: /docs/migration | Type: guide | Summary: Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
|
|
11
11
|
- [Choose a Geistdocs package](pages/packages.md) | URL: /docs/packages | Type: guide | Summary: Use the public package by default and the private package only where restricted Vercel npm dependencies are already available.
|
|
12
12
|
- [Configuration](pages/configuration.md) | URL: /docs/configuration | Type: reference | Summary: Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
|
|
13
|
-
- [MDX Components](pages/syntax.md) | URL: /docs/syntax | Type: reference | Summary: MDX component and authoring reference covering tabs, text formatting, code blocks, line highlighting
|
|
13
|
+
- [MDX Components](pages/syntax.md) | URL: /docs/syntax | Type: reference | Summary: MDX component and authoring reference covering tabs, text formatting, code blocks, and line highlighting.
|
|
14
14
|
- [Geistdocs Provider](pages/provider.md) | URL: /docs/provider | Type: reference | Summary: The root provider component that wraps your application to handle toast notifications, search, and analytics.
|
|
15
15
|
- [Versioned docs](pages/versioned-docs.md) | URL: /docs/versioned-docs | Type: guide | Summary: Use createVersionedSources to configure stable, pre-release, or host-based documentation versions.
|
|
16
16
|
- [Proxy and markdown routes](pages/proxy.md) | URL: /docs/proxy | Type: reference | Summary: Configure createProxy with generated route discovery, request hooks, markdown mappings, and a static Next.js matcher.
|
|
@@ -37,7 +37,6 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
|
|
|
37
37
|
- [Input](pages/components/input.md) | URL: /docs/components/input | Type: reference | Summary: Use Input for text entry in custom documentation and application interfaces.
|
|
38
38
|
- [Internationalization](pages/internationalization.md) | URL: /docs/internationalization | Type: guide | Summary: Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
|
|
39
39
|
- [llms.txt](pages/llms-txt.md) | URL: /docs/llms-txt | Type: conceptual | Summary: A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
|
|
40
|
-
- [Mermaid](pages/components/mermaid.md) | URL: /docs/components/mermaid | Type: reference | Summary: Use Mermaid directly when diagram source is assembled outside an MDX Mermaid fence.
|
|
41
40
|
- [Native Link](pages/components/link.md) | URL: /docs/components/link | Type: reference | Summary: Use NativeDocsLink where Next.js client navigation is not appropriate.
|
|
42
41
|
- [Navigation Menu](pages/components/navigation-menu.md) | URL: /docs/components/navigation-menu | Type: reference | Summary: Compose NavigationMenu primitives for custom product and documentation navigation.
|
|
43
42
|
- [Open in Chat](pages/open-in-chat.md) | URL: /docs/open-in-chat | Type: conceptual | Summary: Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
|
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": "
|
|
4
|
+
"version": "3.0.0",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -41,9 +41,7 @@
|
|
|
41
41
|
"shared-theme.css",
|
|
42
42
|
"styles.css",
|
|
43
43
|
"theme.css",
|
|
44
|
-
"LICENSE"
|
|
45
|
-
"search-index.js",
|
|
46
|
-
"search-index.d.ts"
|
|
44
|
+
"LICENSE"
|
|
47
45
|
],
|
|
48
46
|
"exports": {
|
|
49
47
|
"./changelog": {
|
|
@@ -307,14 +305,9 @@
|
|
|
307
305
|
"./theme.css": "./theme.css",
|
|
308
306
|
"./package.json": "./package.json"
|
|
309
307
|
},
|
|
310
|
-
"scripts": {
|
|
311
|
-
"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",
|
|
312
|
-
"dev": "tsc -p tsconfig.runtime.json --watch --preserveWatchOutput"
|
|
313
|
-
},
|
|
314
308
|
"dependencies": {
|
|
315
309
|
"@ai-sdk/react": "^3.0.134",
|
|
316
310
|
"@clack/prompts": "^0.11.0",
|
|
317
|
-
"@mdx-js/mdx": "^3.1.1",
|
|
318
311
|
"@modelcontextprotocol/server": "^2.0.0",
|
|
319
312
|
"@next/env": "16.3.3",
|
|
320
313
|
"@orama/tokenizers": "^3.1.16",
|
|
@@ -336,9 +329,7 @@
|
|
|
336
329
|
"fumadocs-ui": "16.2.2",
|
|
337
330
|
"geist": "1.7.1",
|
|
338
331
|
"glob": "^11.0.0",
|
|
339
|
-
"js-yaml": "^4.1.1",
|
|
340
332
|
"mcp-handler": "2.2.0",
|
|
341
|
-
"mermaid": "^11.12.2",
|
|
342
333
|
"next-themes": "^0.4.6",
|
|
343
334
|
"phase": "^0.5.4",
|
|
344
335
|
"radix-ui": "1.6.4",
|
|
@@ -353,17 +344,16 @@
|
|
|
353
344
|
"sonner": "^2.0.8",
|
|
354
345
|
"streamdown": "^2.1.0",
|
|
355
346
|
"tailwind-merge": "^3.4.0",
|
|
356
|
-
"tinyglobby": "^0.2.15",
|
|
357
347
|
"ts-morph": "^27.0.2",
|
|
358
348
|
"tw-animate-css": "^1.4.0",
|
|
359
349
|
"unified": "^11.0.5",
|
|
360
350
|
"unist-util-visit": "^5.1.0",
|
|
361
351
|
"use-stick-to-bottom": "^1.1.1",
|
|
362
352
|
"vaul": "^1.1.2",
|
|
363
|
-
"vfile": "^6.0.3",
|
|
364
353
|
"zod": "^4.6.5"
|
|
365
354
|
},
|
|
366
355
|
"peerDependencies": {
|
|
356
|
+
"mermaid": "^11.12.2",
|
|
367
357
|
"next": "^16.3.3",
|
|
368
358
|
"react": "^19.2.3",
|
|
369
359
|
"react-dom": "^19.2.3",
|
|
@@ -376,10 +366,20 @@
|
|
|
376
366
|
"@types/node": "^24.10.1",
|
|
377
367
|
"@types/react-dom": "^19.2.3",
|
|
378
368
|
"mdast-util-mdx-jsx": "^3.2.0",
|
|
369
|
+
"mermaid": "^11.12.2",
|
|
379
370
|
"next": "16.3.3",
|
|
380
371
|
"react": "^19.2.3",
|
|
381
372
|
"react-dom": "^19.2.3",
|
|
382
373
|
"tsup": "^8.5.1",
|
|
383
374
|
"typescript": "^5.9.3"
|
|
375
|
+
},
|
|
376
|
+
"peerDependenciesMeta": {
|
|
377
|
+
"mermaid": {
|
|
378
|
+
"optional": true
|
|
379
|
+
}
|
|
380
|
+
},
|
|
381
|
+
"scripts": {
|
|
382
|
+
"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",
|
|
383
|
+
"dev": "tsc -p tsconfig.runtime.json --watch --preserveWatchOutput"
|
|
384
384
|
}
|
|
385
|
-
}
|
|
385
|
+
}
|
package/source-config.js
CHANGED
|
@@ -17,7 +17,6 @@ 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";
|
|
21
20
|
|
|
22
21
|
// Mirrors src/internal/last-modified.ts. This file must stay dependency-free
|
|
23
22
|
// on dist so source.config.ts can load it before the package is built.
|
|
@@ -308,7 +307,6 @@ export const defineGeistdocsSourceConfig = (config = {}) => {
|
|
|
308
307
|
plugins: [
|
|
309
308
|
lastModified({ versionControl: getLastModified }),
|
|
310
309
|
...existingPlugins,
|
|
311
|
-
...(config.searchIndex ? [searchIndex()] : []),
|
|
312
310
|
],
|
|
313
311
|
});
|
|
314
312
|
};
|
package/template/AGENTS.md
CHANGED
|
@@ -108,10 +108,6 @@ 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
|
-
|
|
115
111
|
## Commands
|
|
116
112
|
|
|
117
113
|
- Start development: `pnpm dev`
|
|
@@ -1,10 +1,5 @@
|
|
|
1
1
|
import { createSearchRoute } from "@vercel/geistdocs/routes/search";
|
|
2
2
|
import { config } from "@/lib/geistdocs/config";
|
|
3
|
+
import { geistdocsSource } from "@/lib/geistdocs/source";
|
|
3
4
|
|
|
4
|
-
export const GET = createSearchRoute({
|
|
5
|
-
config,
|
|
6
|
-
loadSources: async () => {
|
|
7
|
-
const { searchSource } = await import("@/lib/geistdocs/search-source");
|
|
8
|
-
return [searchSource];
|
|
9
|
-
},
|
|
10
|
-
});
|
|
5
|
+
export const GET = createSearchRoute({ config, sources: [geistdocsSource] });
|
|
@@ -80,7 +80,7 @@ export default changelogPage.Page;
|
|
|
80
80
|
|
|
81
81
|
The root adapter uses `Page`, `generateMetadata`, and `generateStaticParams`. The page includes its own `<main>` element, so render it without another main wrapper. Without `getLang`, the helper reads `params.lang`; apps using root parameters should pass their server-side language getter.
|
|
82
82
|
|
|
83
|
-
`config` and `source` are required. `path` defaults to `/changelog`, `title` to `Changelog`, and `description` to `The latest releases, improvements, and fixes.` Set `pageSize` in the shared options; it defaults to `10` and accepts integers from `1` to `100`. Set `markdownPath` only when both Markdown adapters are installed. It enables the shared **Copy page** control
|
|
83
|
+
`config` and `source` are required. `path` defaults to `/changelog`, `title` to `Changelog`, and `description` to `The latest releases, improvements, and fixes.` Set `pageSize` in the shared options; it defaults to `10` and accepts integers from `1` to `100`. Set `markdownPath` only when both Markdown adapters are installed. It enables the shared **Copy page** control (plus **View Markdown** in the mobile row) and alternate metadata; it does not create an endpoint. These actions use the current numbered page's Markdown endpoint and honor `config.pageActions`, matching the docs controls.
|
|
84
84
|
|
|
85
85
|
Keep `path`, `markdownPath`, and `dataPath` app-local, without a locale or deployment `basePath`. Geistdocs adds those prefixes when generating public links and canonical URLs; it does not strip prefixes you supply. Set `config.siteUrl` for absolute canonical URLs.
|
|
86
86
|
|
|
@@ -31,7 +31,6 @@ Internal projects using `@vercel/geistdocs-private` use the same component subpa
|
|
|
31
31
|
| [Image](/docs/components/image) | `components/image` | Next.js images with optional light and dark sources |
|
|
32
32
|
| [Input](/docs/components/input) | `components/input` | Text input fields with provider-backed styling |
|
|
33
33
|
| [Native Link](/docs/components/link) | `components/link` | Styled anchors using browser-native navigation |
|
|
34
|
-
| [Mermaid](/docs/components/mermaid) | `components/mermaid` | Mermaid diagram rendering |
|
|
35
34
|
| [Navigation Menu](/docs/components/navigation-menu) | `components/navigation-menu` | Accessible navigation flyouts |
|
|
36
35
|
| [Popover](/docs/components/popover) | `components/popover` | Anchored floating content |
|
|
37
36
|
| [Scroll Area](/docs/components/scroll-area) | `components/scroll-area` | Styled overflow regions and scrollbars |
|
|
@@ -283,76 +283,6 @@ 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
286
|
### Code highlighter (public package)
|
|
357
287
|
|
|
358
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"`:
|
|
@@ -410,17 +340,17 @@ For example, a root-mounted source with `baseUrl: "/"` still uses `page.url ===
|
|
|
410
340
|
|
|
411
341
|
## Page actions
|
|
412
342
|
|
|
413
|
-
|
|
343
|
+
An icon-only **Copy page** button sits beside the page title. **Give feedback** and **Edit this page on GitHub** sit below the table of contents so they stay available while you read. On mobile, an inline row below the title offers Copy, View Markdown, and Ask AI. These actions are enabled by default and can be disabled through `defineConfig` in `lib/geistdocs/config.tsx`:
|
|
414
344
|
|
|
415
345
|
```tsx title="lib/geistdocs/config.tsx"
|
|
416
346
|
export const config = defineConfig({
|
|
417
347
|
// ...
|
|
418
348
|
pageActions: {
|
|
419
349
|
editSource: false,
|
|
420
|
-
scrollTop: true,
|
|
421
350
|
copyPage: true,
|
|
422
351
|
askAI: true,
|
|
423
|
-
|
|
352
|
+
menu: false,
|
|
353
|
+
openInChat: true,
|
|
424
354
|
},
|
|
425
355
|
feedback: {
|
|
426
356
|
enabled: false,
|
|
@@ -428,6 +358,8 @@ export const config = defineConfig({
|
|
|
428
358
|
});
|
|
429
359
|
```
|
|
430
360
|
|
|
361
|
+
Set `menu: true` to add an actions dropdown beside **Copy page** on desktop, with View as Markdown, Open in v0 and other chats, and Ask AI. The menu is off by default, so sites that don't opt in never download its code. `openInChat` only applies to the menu. Edit on GitHub stays below the table of contents either way.
|
|
362
|
+
|
|
431
363
|
`github.editPath` controls the file path used by the "Edit this page on GitHub" action. Use `{path}` where the page path should be inserted. For monorepos, include the app directory, such as `apps/docs/content/docs/{path}`.
|
|
432
364
|
|
|
433
365
|
## Page visibility
|
|
@@ -574,6 +506,25 @@ const docsPage = createDocsPage({
|
|
|
574
506
|
});
|
|
575
507
|
```
|
|
576
508
|
|
|
509
|
+
### Markdown in custom page headers
|
|
510
|
+
|
|
511
|
+
By default, `renderTop` receives the full page Markdown. If the hook only reads page data, opt out of that conversion:
|
|
512
|
+
|
|
513
|
+
```tsx title="app/[lang]/docs/[[...slug]]/page.tsx"
|
|
514
|
+
const docsPage = createDocsPage({
|
|
515
|
+
config,
|
|
516
|
+
source: geistdocsSource,
|
|
517
|
+
renderTopMarkdown: false,
|
|
518
|
+
renderTop: ({ data }) => <MobileDocsBar toc={data.toc} />,
|
|
519
|
+
});
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
`renderTopMarkdown` defaults to `true` for backward compatibility. Setting it to `false` passes `markdown: ""` to `renderTop`, unless `pageActions.getExtraActions` also needs Markdown; in that case both hooks receive the full Markdown. Leave the default when your header reads `markdown`.
|
|
523
|
+
|
|
524
|
+
Both package variants support this option. Newly generated sites opt out for their TOC-only header. Existing consumers can add `renderTopMarkdown: false` to their local `createDocsPage` call after confirming that `renderTop` does not use Markdown. Updating the package does not overwrite local adapters. This option does not change per-page Markdown routes, `llms.txt`, search exports, or metadata.
|
|
525
|
+
|
|
526
|
+
### Page URLs and metadata
|
|
527
|
+
|
|
577
528
|
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`.
|
|
578
529
|
|
|
579
530
|
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.
|
|
@@ -7,7 +7,7 @@ related:
|
|
|
7
7
|
- /docs/configuration
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
-
The "Edit on GitHub" feature gives readers a direct link to propose documentation changes. This link appears
|
|
10
|
+
The "Edit on GitHub" feature gives readers a direct link to propose documentation changes. This link appears below the table of contents, next to **Give feedback**, on every documentation page that has a table of contents.
|
|
11
11
|
|
|
12
12
|
<CopyPrompt text="Help me configure Edit on GitHub for this Geistdocs site. Check the github owner and repo in geistdocs.tsx, verify the generated edit URL for this page, and tell me how to disable the action if needed.">
|
|
13
13
|
Help me configure Edit on GitHub for this Geistdocs site. Check the `github` owner and repo in `geistdocs.tsx`, verify the generated edit URL for this page, and tell me how to disable the action if needed.
|
|
@@ -23,34 +23,6 @@ Geistdocs has three main parts:
|
|
|
23
23
|
- Local adapter files: The files in your generated project that connect your configuration, content source, routes, and UI customization to the package.
|
|
24
24
|
- Platform services: Hosted endpoints at `geistdocs.com` for optional translation, feedback, and markdown tracking features.
|
|
25
25
|
|
|
26
|
-
```mermaid
|
|
27
|
-
flowchart TB
|
|
28
|
-
subgraph Package["@vercel/geistdocs package"]
|
|
29
|
-
cli["CLI: init, update, translate, search sync"]
|
|
30
|
-
runtime["Runtime: layout, routes, MDX, controls"]
|
|
31
|
-
bundledTemplate["Bundled template snapshot"]
|
|
32
|
-
end
|
|
33
|
-
|
|
34
|
-
subgraph Site["Generated docs site"]
|
|
35
|
-
config["geistdocs.tsx"]
|
|
36
|
-
adapters["app/, components/geistdocs/, lib/geistdocs/"]
|
|
37
|
-
content["content/docs/*.mdx"]
|
|
38
|
-
end
|
|
39
|
-
|
|
40
|
-
subgraph Platform["Geistdocs platform"]
|
|
41
|
-
translate["/translate"]
|
|
42
|
-
feedback["/feedback"]
|
|
43
|
-
tracking["/md-tracking"]
|
|
44
|
-
end
|
|
45
|
-
|
|
46
|
-
cli --> bundledTemplate
|
|
47
|
-
bundledTemplate --> Site
|
|
48
|
-
adapters --> runtime
|
|
49
|
-
content --> adapters
|
|
50
|
-
cli --> translate
|
|
51
|
-
runtime --> feedback
|
|
52
|
-
runtime --> tracking
|
|
53
|
-
```
|
|
54
26
|
|
|
55
27
|
## What you edit
|
|
56
28
|
|
|
@@ -37,7 +37,7 @@ The `.mdx` version returns:
|
|
|
37
37
|
|
|
38
38
|
For a docs section mounted at `/docs`, the section root remains `/docs.md`. For a source mounted at the app root with `baseUrl: "/"`, Geistdocs uses `/index.md` for the root page. If Next.js has `basePath: "/docs"`, that public root Markdown URL is `/docs/index.md`.
|
|
39
39
|
|
|
40
|
-
Copy Page, View
|
|
40
|
+
Copy Page, View Markdown, and the `text/markdown` metadata alternate all use the same package resolver. View Markdown, in the mobile page actions row, opens the resolved `.md` URL in a new tab from a button, which keeps the URL shareable without adding an anchor to the page. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
|
|
41
41
|
|
|
42
42
|
## Use cases
|
|
43
43
|
|
|
@@ -118,7 +118,7 @@ Replace imports according to this table:
|
|
|
118
118
|
| `assets/icons`, `assets/icons/*`, `assets/logos`, or `assets/logos/*` | Keep the import package-backed. Both Geistdocs package variants expose the index and deep asset subpaths. |
|
|
119
119
|
| `components/button-group`, `components/card`, or `components/input-group` | Use an appropriate Geistcn component or keep an application-owned composition. There is no direct Geistcn replacement with the same API. |
|
|
120
120
|
|
|
121
|
-
Keep documentation-specific composites such as `Callout`, `CodeBlock`, `CodeBlockTabs`, `CommandPrompt`,
|
|
121
|
+
Keep documentation-specific composites such as `Callout`, `CodeBlock`, `CodeBlockTabs`, `CommandPrompt`, and `CopyPrompt` imported from `@vercel/geistdocs/components/*`.
|
|
122
122
|
|
|
123
123
|
## Configure Next.js
|
|
124
124
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
title: MDX 组件
|
|
3
3
|
description: 使用支持的组件、Markdown 语法和格式选项编写 MDX 内容
|
|
4
4
|
type: reference
|
|
5
|
-
summary: MDX
|
|
5
|
+
summary: MDX 组件和编写参考,包括文本格式、代码块和行高亮。
|
|
6
6
|
prerequisites:
|
|
7
7
|
- /docs/getting-started
|
|
8
8
|
related:
|
|
@@ -361,109 +361,3 @@ const numbers = [1, 2, 3, 4, 5];
|
|
|
361
361
|
const sum = numbers.reduce((a, b) => a + b, 0); // [!code focus]
|
|
362
362
|
console.log(sum);
|
|
363
363
|
```
|
|
364
|
-
|
|
365
|
-
## Mermaid 图表
|
|
366
|
-
|
|
367
|
-
使用 Mermaid 语法创建图表和流程图。
|
|
368
|
-
|
|
369
|
-
### 流程图
|
|
370
|
-
|
|
371
|
-
````md
|
|
372
|
-
```mermaid
|
|
373
|
-
graph TD;
|
|
374
|
-
A[Start] --> B{Is it working?};
|
|
375
|
-
B -->|Yes| C[Great!];
|
|
376
|
-
B -->|No| D[Debug];
|
|
377
|
-
D --> B;
|
|
378
|
-
```
|
|
379
|
-
````
|
|
380
|
-
|
|
381
|
-
渲染为:
|
|
382
|
-
|
|
383
|
-
```mermaid
|
|
384
|
-
graph TD;
|
|
385
|
-
A[Start] --> B{Is it working?};
|
|
386
|
-
B -->|Yes| C[Great!];
|
|
387
|
-
B -->|No| D[Debug];
|
|
388
|
-
D --> B;
|
|
389
|
-
```
|
|
390
|
-
|
|
391
|
-
### 时序图
|
|
392
|
-
|
|
393
|
-
````md
|
|
394
|
-
```mermaid
|
|
395
|
-
sequenceDiagram
|
|
396
|
-
participant User
|
|
397
|
-
participant API
|
|
398
|
-
participant Database
|
|
399
|
-
User->>API: Request data
|
|
400
|
-
API->>Database: Query
|
|
401
|
-
Database-->>API: Results
|
|
402
|
-
API-->>User: Response
|
|
403
|
-
```
|
|
404
|
-
````
|
|
405
|
-
|
|
406
|
-
渲染为:
|
|
407
|
-
|
|
408
|
-
```mermaid
|
|
409
|
-
sequenceDiagram
|
|
410
|
-
participant User
|
|
411
|
-
participant API
|
|
412
|
-
participant Database
|
|
413
|
-
User->>API: Request data
|
|
414
|
-
API->>Database: Query
|
|
415
|
-
Database-->>API: Results
|
|
416
|
-
API-->>User: Response
|
|
417
|
-
```
|
|
418
|
-
|
|
419
|
-
### 架构图
|
|
420
|
-
|
|
421
|
-
````md
|
|
422
|
-
```mermaid
|
|
423
|
-
graph TD;
|
|
424
|
-
subgraph Frontend
|
|
425
|
-
A[Web App]
|
|
426
|
-
B[Mobile App]
|
|
427
|
-
end
|
|
428
|
-
subgraph Backend
|
|
429
|
-
C[API Gateway]
|
|
430
|
-
D[Auth Service]
|
|
431
|
-
E[Data Service]
|
|
432
|
-
end
|
|
433
|
-
subgraph Storage
|
|
434
|
-
F[(Database)]
|
|
435
|
-
G[(Cache)]
|
|
436
|
-
end
|
|
437
|
-
A --> C
|
|
438
|
-
B --> C
|
|
439
|
-
C --> D
|
|
440
|
-
C --> E
|
|
441
|
-
E --> F
|
|
442
|
-
E --> G
|
|
443
|
-
```
|
|
444
|
-
````
|
|
445
|
-
|
|
446
|
-
渲染为:
|
|
447
|
-
|
|
448
|
-
```mermaid
|
|
449
|
-
graph TD;
|
|
450
|
-
subgraph Frontend
|
|
451
|
-
A[Web App]
|
|
452
|
-
B[Mobile App]
|
|
453
|
-
end
|
|
454
|
-
subgraph Backend
|
|
455
|
-
C[API Gateway]
|
|
456
|
-
D[Auth Service]
|
|
457
|
-
E[Data Service]
|
|
458
|
-
end
|
|
459
|
-
subgraph Storage
|
|
460
|
-
F[(Database)]
|
|
461
|
-
G[(Cache)]
|
|
462
|
-
end
|
|
463
|
-
A --> C
|
|
464
|
-
B --> C
|
|
465
|
-
C --> D
|
|
466
|
-
C --> E
|
|
467
|
-
E --> F
|
|
468
|
-
E --> G
|
|
469
|
-
```
|