@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/llms.txt
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Geistdocs Package Documentation
|
|
2
2
|
|
|
3
|
-
These docs are bundled with `@vercel/geistdocs`
|
|
3
|
+
These docs are bundled with `@vercel/geistdocs` 3.0.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
|
|
@@ -12,7 +12,7 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
|
|
|
12
12
|
- [Migrate to Geistdocs](pages/migration.md): Move an existing documentation site to @vercel/geistdocs while keeping local content, routing, middleware behavior, and AI-readable surfaces intact.
|
|
13
13
|
- [Choose a Geistdocs package](pages/packages.md): Use the public package by default and the private package only where restricted Vercel npm dependencies are already available.
|
|
14
14
|
- [Configuration](pages/configuration.md): Configure site metadata, navigation, AI features, page actions, translations, and local adapters.
|
|
15
|
-
- [MDX Components](pages/syntax.md): MDX component and authoring reference covering tabs, text formatting, code blocks, line highlighting
|
|
15
|
+
- [MDX Components](pages/syntax.md): MDX component and authoring reference covering tabs, text formatting, code blocks, and line highlighting.
|
|
16
16
|
- [Geistdocs Provider](pages/provider.md): The root provider component that wraps your application to handle toast notifications, search, and analytics.
|
|
17
17
|
- [Versioned docs](pages/versioned-docs.md): Use createVersionedSources to configure stable, pre-release, or host-based documentation versions.
|
|
18
18
|
- [Proxy and markdown routes](pages/proxy.md): Configure createProxy with generated route discovery, request hooks, markdown mappings, and a static Next.js matcher.
|
|
@@ -39,7 +39,6 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
|
|
|
39
39
|
- [Input](pages/components/input.md): Use Input for text entry in custom documentation and application interfaces.
|
|
40
40
|
- [Internationalization](pages/internationalization.md): Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
|
|
41
41
|
- [llms.txt](pages/llms-txt.md): A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
|
|
42
|
-
- [Mermaid](pages/components/mermaid.md): Use Mermaid directly when diagram source is assembled outside an MDX Mermaid fence.
|
|
43
42
|
- [Native Link](pages/components/link.md): Use NativeDocsLink where Next.js client navigation is not appropriate.
|
|
44
43
|
- [Navigation Menu](pages/components/navigation-menu.md): Compose NavigationMenu primitives for custom product and documentation navigation.
|
|
45
44
|
- [Open in Chat](pages/open-in-chat.md): Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
|
|
@@ -86,35 +85,6 @@ Geistdocs has three main parts:
|
|
|
86
85
|
- Local adapter files: The files in your generated project that connect your configuration, content source, routes, and UI customization to the package.
|
|
87
86
|
- Platform services: Hosted endpoints at `geistdocs.com` for optional translation, feedback, and markdown tracking features.
|
|
88
87
|
|
|
89
|
-
```mermaid
|
|
90
|
-
flowchart TB
|
|
91
|
-
subgraph Package["@vercel/geistdocs package"]
|
|
92
|
-
cli["CLI: init, update, translate, search sync"]
|
|
93
|
-
runtime["Runtime: layout, routes, MDX, controls"]
|
|
94
|
-
bundledTemplate["Bundled template snapshot"]
|
|
95
|
-
end
|
|
96
|
-
|
|
97
|
-
subgraph Site["Generated docs site"]
|
|
98
|
-
config["geistdocs.tsx"]
|
|
99
|
-
adapters["app/, components/geistdocs/, lib/geistdocs/"]
|
|
100
|
-
content["content/docs/*.mdx"]
|
|
101
|
-
end
|
|
102
|
-
|
|
103
|
-
subgraph Platform["Geistdocs platform"]
|
|
104
|
-
translate["/translate"]
|
|
105
|
-
feedback["/feedback"]
|
|
106
|
-
tracking["/md-tracking"]
|
|
107
|
-
end
|
|
108
|
-
|
|
109
|
-
cli --> bundledTemplate
|
|
110
|
-
bundledTemplate --> Site
|
|
111
|
-
adapters --> runtime
|
|
112
|
-
content --> adapters
|
|
113
|
-
cli --> translate
|
|
114
|
-
runtime --> feedback
|
|
115
|
-
runtime --> tracking
|
|
116
|
-
```
|
|
117
|
-
|
|
118
88
|
## What you edit
|
|
119
89
|
|
|
120
90
|
Most projects start by editing these files:
|
|
@@ -628,7 +598,7 @@ Replace imports according to this table:
|
|
|
628
598
|
| `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. |
|
|
629
599
|
| `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. |
|
|
630
600
|
|
|
631
|
-
Keep documentation-specific composites such as `Callout`, `CodeBlock`, `CodeBlockTabs`, `CommandPrompt`,
|
|
601
|
+
Keep documentation-specific composites such as `Callout`, `CodeBlock`, `CodeBlockTabs`, `CommandPrompt`, and `CopyPrompt` imported from `@vercel/geistdocs/components/*`.
|
|
632
602
|
|
|
633
603
|
## Configure Next.js
|
|
634
604
|
|
|
@@ -1424,76 +1394,6 @@ export const docs = defineDocs({
|
|
|
1424
1394
|
export default defineGeistdocsSourceConfig();
|
|
1425
1395
|
```
|
|
1426
1396
|
|
|
1427
|
-
### Search-only collections
|
|
1428
|
-
|
|
1429
|
-
Enable generation of search data without compiled page bodies:
|
|
1430
|
-
|
|
1431
|
-
```ts title="source.config.ts"
|
|
1432
|
-
export default defineGeistdocsSourceConfig({ searchIndex: true });
|
|
1433
|
-
```
|
|
1434
|
-
|
|
1435
|
-
Also enable preparation in the Next wrapper. It waits for codegen before bundling
|
|
1436
|
-
and skips source extraction in `next start`:
|
|
1437
|
-
|
|
1438
|
-
```ts title="next.config.ts"
|
|
1439
|
-
const withGeistdocs = createGeistdocs({ searchIndex: true });
|
|
1440
|
-
export default withGeistdocs(config);
|
|
1441
|
-
```
|
|
1442
|
-
|
|
1443
|
-
With this option, the wrapper returns a phase-aware Next config function. Export
|
|
1444
|
-
it directly as above; apply other Next config wrappers to `config` first.
|
|
1445
|
-
|
|
1446
|
-
Run your existing `fumadocs-mdx` postinstall command to generate
|
|
1447
|
-
`.source/search/<collection>.ts`. Each module exports a collection compatible
|
|
1448
|
-
with `createSource`; its frontmatter, sections, and metadata contain no MDX
|
|
1449
|
-
imports. Keep the same source options (base URL, slugs, locales, page-tree
|
|
1450
|
-
customization) as your rendering source, in a shared module that does not import
|
|
1451
|
-
`.source/server`.
|
|
1452
|
-
|
|
1453
|
-
```ts title="lib/geistdocs/search-source.ts"
|
|
1454
|
-
import { createSource } from "@vercel/geistdocs/source";
|
|
1455
|
-
import docs from "@/.source/search/docs";
|
|
1456
|
-
import { config } from "./config";
|
|
1457
|
-
|
|
1458
|
-
export const searchSource = createSource({ docs, config });
|
|
1459
|
-
```
|
|
1460
|
-
|
|
1461
|
-
```ts title="app/api/search/route.ts"
|
|
1462
|
-
import { createSearchRoute } from "@vercel/geistdocs/routes/search";
|
|
1463
|
-
import { config } from "@/lib/geistdocs/config";
|
|
1464
|
-
|
|
1465
|
-
export const GET = createSearchRoute({
|
|
1466
|
-
config,
|
|
1467
|
-
loadSources: async () => {
|
|
1468
|
-
const { searchSource } = await import("@/lib/geistdocs/search-source");
|
|
1469
|
-
return [searchSource];
|
|
1470
|
-
},
|
|
1471
|
-
});
|
|
1472
|
-
```
|
|
1473
|
-
|
|
1474
|
-
Use either `loadSources` or the existing `source`/`sources` options. Concurrent
|
|
1475
|
-
requests share initialization; a failed initialization can be retried. Only the
|
|
1476
|
-
requested locale's indexes are built. For versioned sites, create one lazy route
|
|
1477
|
-
per version and dispatch to it using your existing version selector. Do not
|
|
1478
|
-
import a barrel that also loads the rendering sources.
|
|
1479
|
-
|
|
1480
|
-
The generator runs the collection's schemas, frontmatter/VFile/metadata hooks,
|
|
1481
|
-
and resolved remark plugins, including Markdown includes. It skips highlighting,
|
|
1482
|
-
rehype, and recma, and adds a separate remark pass during codegen. Custom search
|
|
1483
|
-
content must be recorded in `structuredData` by the remark pipeline. Collection
|
|
1484
|
-
MDX overrides must retain `remarkStructure`. Metadata must serialize as JSON
|
|
1485
|
-
values or Dates; custom runtime exports, page bodies, and Markdown methods are
|
|
1486
|
-
not available on search-only pages. Filters must use stable metadata, not render
|
|
1487
|
-
or load page bodies. Keep generated modules server-only: internal pages and
|
|
1488
|
-
custom metadata may be present, with `internal`, `excludeFrom`, and `filterPage`
|
|
1489
|
-
applied by the search route before returning results.
|
|
1490
|
-
|
|
1491
|
-
This works in development, previews, and production, in both packages. Content,
|
|
1492
|
-
metadata, and registered include dependencies regenerate on edits; generation
|
|
1493
|
-
errors invalidate old output and fail production/codegen commands. Orama still
|
|
1494
|
-
builds its indexes on first search. Keep `.source/server` for docs rendering,
|
|
1495
|
-
Markdown exports, and chat.
|
|
1496
|
-
|
|
1497
1397
|
### Code highlighter (public package)
|
|
1498
1398
|
|
|
1499
1399
|
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"`:
|
|
@@ -1551,17 +1451,17 @@ For example, a root-mounted source with `baseUrl: "/"` still uses `page.url ===
|
|
|
1551
1451
|
|
|
1552
1452
|
## Page actions
|
|
1553
1453
|
|
|
1554
|
-
|
|
1454
|
+
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`:
|
|
1555
1455
|
|
|
1556
1456
|
```tsx title="lib/geistdocs/config.tsx"
|
|
1557
1457
|
export const config = defineConfig({
|
|
1558
1458
|
// ...
|
|
1559
1459
|
pageActions: {
|
|
1560
1460
|
editSource: false,
|
|
1561
|
-
scrollTop: true,
|
|
1562
1461
|
copyPage: true,
|
|
1563
1462
|
askAI: true,
|
|
1564
|
-
|
|
1463
|
+
menu: false,
|
|
1464
|
+
openInChat: true,
|
|
1565
1465
|
},
|
|
1566
1466
|
feedback: {
|
|
1567
1467
|
enabled: false,
|
|
@@ -1569,6 +1469,8 @@ export const config = defineConfig({
|
|
|
1569
1469
|
});
|
|
1570
1470
|
```
|
|
1571
1471
|
|
|
1472
|
+
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.
|
|
1473
|
+
|
|
1572
1474
|
`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}`.
|
|
1573
1475
|
|
|
1574
1476
|
## Page visibility
|
|
@@ -1715,6 +1617,25 @@ const docsPage = createDocsPage({
|
|
|
1715
1617
|
});
|
|
1716
1618
|
```
|
|
1717
1619
|
|
|
1620
|
+
### Markdown in custom page headers
|
|
1621
|
+
|
|
1622
|
+
By default, `renderTop` receives the full page Markdown. If the hook only reads page data, opt out of that conversion:
|
|
1623
|
+
|
|
1624
|
+
```tsx title="app/[lang]/docs/[[...slug]]/page.tsx"
|
|
1625
|
+
const docsPage = createDocsPage({
|
|
1626
|
+
config,
|
|
1627
|
+
source: geistdocsSource,
|
|
1628
|
+
renderTopMarkdown: false,
|
|
1629
|
+
renderTop: ({ data }) => <MobileDocsBar toc={data.toc} />,
|
|
1630
|
+
});
|
|
1631
|
+
```
|
|
1632
|
+
|
|
1633
|
+
`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`.
|
|
1634
|
+
|
|
1635
|
+
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.
|
|
1636
|
+
|
|
1637
|
+
### Page URLs and metadata
|
|
1638
|
+
|
|
1718
1639
|
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`.
|
|
1719
1640
|
|
|
1720
1641
|
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.
|
|
@@ -1744,7 +1665,7 @@ If a release adds an optional prop or config field, opt into it by editing the r
|
|
|
1744
1665
|
title: MDX Components
|
|
1745
1666
|
description: Author MDX content with supported components, Markdown syntax, and formatting options
|
|
1746
1667
|
type: reference
|
|
1747
|
-
summary: MDX component and authoring reference covering tabs, text formatting, code blocks, line highlighting
|
|
1668
|
+
summary: MDX component and authoring reference covering tabs, text formatting, code blocks, and line highlighting.
|
|
1748
1669
|
url: /docs/syntax
|
|
1749
1670
|
source: apps/template/content/docs/syntax.mdx
|
|
1750
1671
|
prerequisites:
|
|
@@ -2455,112 +2376,6 @@ const sum = numbers.reduce((a, b) => a + b, 0); // [!code focus]
|
|
|
2455
2376
|
console.log(sum);
|
|
2456
2377
|
```
|
|
2457
2378
|
|
|
2458
|
-
## Mermaid Diagrams
|
|
2459
|
-
|
|
2460
|
-
Create diagrams and flowcharts using Mermaid syntax.
|
|
2461
|
-
|
|
2462
|
-
### Flowcharts
|
|
2463
|
-
|
|
2464
|
-
````md
|
|
2465
|
-
```mermaid
|
|
2466
|
-
graph TD;
|
|
2467
|
-
A[Start] --> B{Is it working?};
|
|
2468
|
-
B -->|Yes| C[Great!];
|
|
2469
|
-
B -->|No| D[Debug];
|
|
2470
|
-
D --> B;
|
|
2471
|
-
```
|
|
2472
|
-
````
|
|
2473
|
-
|
|
2474
|
-
This renders as:
|
|
2475
|
-
|
|
2476
|
-
```mermaid
|
|
2477
|
-
graph TD;
|
|
2478
|
-
A[Start] --> B{Is it working?};
|
|
2479
|
-
B -->|Yes| C[Great!];
|
|
2480
|
-
B -->|No| D[Debug];
|
|
2481
|
-
D --> B;
|
|
2482
|
-
```
|
|
2483
|
-
|
|
2484
|
-
### Sequence Diagrams
|
|
2485
|
-
|
|
2486
|
-
````md
|
|
2487
|
-
```mermaid
|
|
2488
|
-
sequenceDiagram
|
|
2489
|
-
participant User
|
|
2490
|
-
participant API
|
|
2491
|
-
participant Database
|
|
2492
|
-
User->>API: Request data
|
|
2493
|
-
API->>Database: Query
|
|
2494
|
-
Database-->>API: Results
|
|
2495
|
-
API-->>User: Response
|
|
2496
|
-
```
|
|
2497
|
-
````
|
|
2498
|
-
|
|
2499
|
-
This renders as:
|
|
2500
|
-
|
|
2501
|
-
```mermaid
|
|
2502
|
-
sequenceDiagram
|
|
2503
|
-
participant User
|
|
2504
|
-
participant API
|
|
2505
|
-
participant Database
|
|
2506
|
-
User->>API: Request data
|
|
2507
|
-
API->>Database: Query
|
|
2508
|
-
Database-->>API: Results
|
|
2509
|
-
API-->>User: Response
|
|
2510
|
-
```
|
|
2511
|
-
|
|
2512
|
-
### Architecture Diagrams
|
|
2513
|
-
|
|
2514
|
-
````md
|
|
2515
|
-
```mermaid
|
|
2516
|
-
graph TD;
|
|
2517
|
-
subgraph Frontend
|
|
2518
|
-
A[Web App]
|
|
2519
|
-
B[Mobile App]
|
|
2520
|
-
end
|
|
2521
|
-
subgraph Backend
|
|
2522
|
-
C[API Gateway]
|
|
2523
|
-
D[Auth Service]
|
|
2524
|
-
E[Data Service]
|
|
2525
|
-
end
|
|
2526
|
-
subgraph Storage
|
|
2527
|
-
F[(Database)]
|
|
2528
|
-
G[(Cache)]
|
|
2529
|
-
end
|
|
2530
|
-
A --> C
|
|
2531
|
-
B --> C
|
|
2532
|
-
C --> D
|
|
2533
|
-
C --> E
|
|
2534
|
-
E --> F
|
|
2535
|
-
E --> G
|
|
2536
|
-
```
|
|
2537
|
-
````
|
|
2538
|
-
|
|
2539
|
-
This renders as:
|
|
2540
|
-
|
|
2541
|
-
```mermaid
|
|
2542
|
-
graph TD;
|
|
2543
|
-
subgraph Frontend
|
|
2544
|
-
A[Web App]
|
|
2545
|
-
B[Mobile App]
|
|
2546
|
-
end
|
|
2547
|
-
subgraph Backend
|
|
2548
|
-
C[API Gateway]
|
|
2549
|
-
D[Auth Service]
|
|
2550
|
-
E[Data Service]
|
|
2551
|
-
end
|
|
2552
|
-
subgraph Storage
|
|
2553
|
-
F[(Database)]
|
|
2554
|
-
G[(Cache)]
|
|
2555
|
-
end
|
|
2556
|
-
A --> C
|
|
2557
|
-
B --> C
|
|
2558
|
-
C --> D
|
|
2559
|
-
C --> E
|
|
2560
|
-
E --> F
|
|
2561
|
-
E --> G
|
|
2562
|
-
```
|
|
2563
|
-
|
|
2564
2379
|
|
|
2565
2380
|
---
|
|
2566
2381
|
|
|
@@ -3354,7 +3169,7 @@ export default changelogPage.Page;
|
|
|
3354
3169
|
|
|
3355
3170
|
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.
|
|
3356
3171
|
|
|
3357
|
-
`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
|
|
3172
|
+
`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.
|
|
3358
3173
|
|
|
3359
3174
|
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.
|
|
3360
3175
|
|
|
@@ -3699,7 +3514,7 @@ The `.mdx` version returns:
|
|
|
3699
3514
|
|
|
3700
3515
|
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`.
|
|
3701
3516
|
|
|
3702
|
-
Copy Page, View
|
|
3517
|
+
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.
|
|
3703
3518
|
|
|
3704
3519
|
## Use cases
|
|
3705
3520
|
|
|
@@ -5178,7 +4993,6 @@ Internal projects using `@vercel/geistdocs-private` use the same component subpa
|
|
|
5178
4993
|
| [Image](/docs/components/image) | `components/image` | Next.js images with optional light and dark sources |
|
|
5179
4994
|
| [Input](/docs/components/input) | `components/input` | Text input fields with provider-backed styling |
|
|
5180
4995
|
| [Native Link](/docs/components/link) | `components/link` | Styled anchors using browser-native navigation |
|
|
5181
|
-
| [Mermaid](/docs/components/mermaid) | `components/mermaid` | Mermaid diagram rendering |
|
|
5182
4996
|
| [Navigation Menu](/docs/components/navigation-menu) | `components/navigation-menu` | Accessible navigation flyouts |
|
|
5183
4997
|
| [Popover](/docs/components/popover) | `components/popover` | Anchored floating content |
|
|
5184
4998
|
| [Scroll Area](/docs/components/scroll-area) | `components/scroll-area` | Styled overflow regions and scrollbars |
|
|
@@ -5643,7 +5457,7 @@ related:
|
|
|
5643
5457
|
|
|
5644
5458
|
# Edit on GitHub
|
|
5645
5459
|
|
|
5646
|
-
The "Edit on GitHub" feature gives readers a direct link to propose documentation changes. This link appears
|
|
5460
|
+
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.
|
|
5647
5461
|
|
|
5648
5462
|
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.
|
|
5649
5463
|
|
|
@@ -6234,39 +6048,6 @@ The llms.txt standard is a simple convention that makes documentation more acces
|
|
|
6234
6048
|
Learn more at [llmstxt.org](https://llmstxt.org/)
|
|
6235
6049
|
|
|
6236
6050
|
|
|
6237
|
-
---
|
|
6238
|
-
|
|
6239
|
-
---
|
|
6240
|
-
title: Mermaid
|
|
6241
|
-
description: Render Mermaid diagrams from chart source
|
|
6242
|
-
type: reference
|
|
6243
|
-
summary: Use Mermaid directly when diagram source is assembled outside an MDX Mermaid fence.
|
|
6244
|
-
url: /docs/components/mermaid
|
|
6245
|
-
source: apps/template/content/docs/components/mermaid.mdx
|
|
6246
|
-
related:
|
|
6247
|
-
- /docs/components
|
|
6248
|
-
- /docs/syntax
|
|
6249
|
-
---
|
|
6250
|
-
|
|
6251
|
-
# Mermaid
|
|
6252
|
-
|
|
6253
|
-
import { Mermaid } from "@vercel/geistdocs/components/mermaid";
|
|
6254
|
-
|
|
6255
|
-
<div className="not-prose my-6 rounded-lg border border-gray-400 bg-background-100 p-6">
|
|
6256
|
-
<Mermaid chart={'graph LR; A["Start"] --> B["Finish"]'} />
|
|
6257
|
-
</div>
|
|
6258
|
-
|
|
6259
|
-
```tsx
|
|
6260
|
-
import { Mermaid } from "@vercel/geistdocs/components/mermaid";
|
|
6261
|
-
|
|
6262
|
-
export function Flow() {
|
|
6263
|
-
return <Mermaid chart={'graph LR; A["Start"] --> B["Finish"]'} />;
|
|
6264
|
-
}
|
|
6265
|
-
```
|
|
6266
|
-
|
|
6267
|
-
Mermaid code fences render this component automatically in authored MDX.
|
|
6268
|
-
|
|
6269
|
-
|
|
6270
6051
|
---
|
|
6271
6052
|
|
|
6272
6053
|
---
|
package/docs/manifest.json
CHANGED
|
@@ -75,7 +75,7 @@
|
|
|
75
75
|
"description": "Author MDX content with supported components, Markdown syntax, and formatting options",
|
|
76
76
|
"path": "pages/syntax.md",
|
|
77
77
|
"source": "apps/template/content/docs/syntax.mdx",
|
|
78
|
-
"summary": "MDX component and authoring reference covering tabs, text formatting, code blocks, line highlighting
|
|
78
|
+
"summary": "MDX component and authoring reference covering tabs, text formatting, code blocks, and line highlighting.",
|
|
79
79
|
"title": "MDX Components",
|
|
80
80
|
"type": "reference",
|
|
81
81
|
"url": "/docs/syntax"
|
|
@@ -314,15 +314,6 @@
|
|
|
314
314
|
"type": "conceptual",
|
|
315
315
|
"url": "/docs/llms-txt"
|
|
316
316
|
},
|
|
317
|
-
{
|
|
318
|
-
"description": "Render Mermaid diagrams from chart source",
|
|
319
|
-
"path": "pages/components/mermaid.md",
|
|
320
|
-
"source": "apps/template/content/docs/components/mermaid.mdx",
|
|
321
|
-
"summary": "Use Mermaid directly when diagram source is assembled outside an MDX Mermaid fence.",
|
|
322
|
-
"title": "Mermaid",
|
|
323
|
-
"type": "reference",
|
|
324
|
-
"url": "/docs/components/mermaid"
|
|
325
|
-
},
|
|
326
317
|
{
|
|
327
318
|
"description": "Render styled anchors with browser-native navigation",
|
|
328
319
|
"path": "pages/components/link.md",
|
|
@@ -467,5 +458,5 @@
|
|
|
467
458
|
}
|
|
468
459
|
],
|
|
469
460
|
"source": "apps/template/content/docs",
|
|
470
|
-
"version": "
|
|
461
|
+
"version": "3.0.0"
|
|
471
462
|
}
|
package/docs/pages/changelog.md
CHANGED
|
@@ -83,7 +83,7 @@ export default changelogPage.Page;
|
|
|
83
83
|
|
|
84
84
|
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.
|
|
85
85
|
|
|
86
|
-
`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
|
|
86
|
+
`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.
|
|
87
87
|
|
|
88
88
|
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.
|
|
89
89
|
|
|
@@ -35,7 +35,6 @@ Internal projects using `@vercel/geistdocs-private` use the same component subpa
|
|
|
35
35
|
| [Image](/docs/components/image) | `components/image` | Next.js images with optional light and dark sources |
|
|
36
36
|
| [Input](/docs/components/input) | `components/input` | Text input fields with provider-backed styling |
|
|
37
37
|
| [Native Link](/docs/components/link) | `components/link` | Styled anchors using browser-native navigation |
|
|
38
|
-
| [Mermaid](/docs/components/mermaid) | `components/mermaid` | Mermaid diagram rendering |
|
|
39
38
|
| [Navigation Menu](/docs/components/navigation-menu) | `components/navigation-menu` | Accessible navigation flyouts |
|
|
40
39
|
| [Popover](/docs/components/popover) | `components/popover` | Anchored floating content |
|
|
41
40
|
| [Scroll Area](/docs/components/scroll-area) | `components/scroll-area` | Styled overflow regions and scrollbars |
|
|
@@ -285,76 +285,6 @@ export const docs = defineDocs({
|
|
|
285
285
|
export default defineGeistdocsSourceConfig();
|
|
286
286
|
```
|
|
287
287
|
|
|
288
|
-
### Search-only collections
|
|
289
|
-
|
|
290
|
-
Enable generation of search data without compiled page bodies:
|
|
291
|
-
|
|
292
|
-
```ts title="source.config.ts"
|
|
293
|
-
export default defineGeistdocsSourceConfig({ searchIndex: true });
|
|
294
|
-
```
|
|
295
|
-
|
|
296
|
-
Also enable preparation in the Next wrapper. It waits for codegen before bundling
|
|
297
|
-
and skips source extraction in `next start`:
|
|
298
|
-
|
|
299
|
-
```ts title="next.config.ts"
|
|
300
|
-
const withGeistdocs = createGeistdocs({ searchIndex: true });
|
|
301
|
-
export default withGeistdocs(config);
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
With this option, the wrapper returns a phase-aware Next config function. Export
|
|
305
|
-
it directly as above; apply other Next config wrappers to `config` first.
|
|
306
|
-
|
|
307
|
-
Run your existing `fumadocs-mdx` postinstall command to generate
|
|
308
|
-
`.source/search/<collection>.ts`. Each module exports a collection compatible
|
|
309
|
-
with `createSource`; its frontmatter, sections, and metadata contain no MDX
|
|
310
|
-
imports. Keep the same source options (base URL, slugs, locales, page-tree
|
|
311
|
-
customization) as your rendering source, in a shared module that does not import
|
|
312
|
-
`.source/server`.
|
|
313
|
-
|
|
314
|
-
```ts title="lib/geistdocs/search-source.ts"
|
|
315
|
-
import { createSource } from "@vercel/geistdocs/source";
|
|
316
|
-
import docs from "@/.source/search/docs";
|
|
317
|
-
import { config } from "./config";
|
|
318
|
-
|
|
319
|
-
export const searchSource = createSource({ docs, config });
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
```ts title="app/api/search/route.ts"
|
|
323
|
-
import { createSearchRoute } from "@vercel/geistdocs/routes/search";
|
|
324
|
-
import { config } from "@/lib/geistdocs/config";
|
|
325
|
-
|
|
326
|
-
export const GET = createSearchRoute({
|
|
327
|
-
config,
|
|
328
|
-
loadSources: async () => {
|
|
329
|
-
const { searchSource } = await import("@/lib/geistdocs/search-source");
|
|
330
|
-
return [searchSource];
|
|
331
|
-
},
|
|
332
|
-
});
|
|
333
|
-
```
|
|
334
|
-
|
|
335
|
-
Use either `loadSources` or the existing `source`/`sources` options. Concurrent
|
|
336
|
-
requests share initialization; a failed initialization can be retried. Only the
|
|
337
|
-
requested locale's indexes are built. For versioned sites, create one lazy route
|
|
338
|
-
per version and dispatch to it using your existing version selector. Do not
|
|
339
|
-
import a barrel that also loads the rendering sources.
|
|
340
|
-
|
|
341
|
-
The generator runs the collection's schemas, frontmatter/VFile/metadata hooks,
|
|
342
|
-
and resolved remark plugins, including Markdown includes. It skips highlighting,
|
|
343
|
-
rehype, and recma, and adds a separate remark pass during codegen. Custom search
|
|
344
|
-
content must be recorded in `structuredData` by the remark pipeline. Collection
|
|
345
|
-
MDX overrides must retain `remarkStructure`. Metadata must serialize as JSON
|
|
346
|
-
values or Dates; custom runtime exports, page bodies, and Markdown methods are
|
|
347
|
-
not available on search-only pages. Filters must use stable metadata, not render
|
|
348
|
-
or load page bodies. Keep generated modules server-only: internal pages and
|
|
349
|
-
custom metadata may be present, with `internal`, `excludeFrom`, and `filterPage`
|
|
350
|
-
applied by the search route before returning results.
|
|
351
|
-
|
|
352
|
-
This works in development, previews, and production, in both packages. Content,
|
|
353
|
-
metadata, and registered include dependencies regenerate on edits; generation
|
|
354
|
-
errors invalidate old output and fail production/codegen commands. Orama still
|
|
355
|
-
builds its indexes on first search. Keep `.source/server` for docs rendering,
|
|
356
|
-
Markdown exports, and chat.
|
|
357
|
-
|
|
358
288
|
### Code highlighter (public package)
|
|
359
289
|
|
|
360
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"`:
|
|
@@ -412,17 +342,17 @@ For example, a root-mounted source with `baseUrl: "/"` still uses `page.url ===
|
|
|
412
342
|
|
|
413
343
|
## Page actions
|
|
414
344
|
|
|
415
|
-
|
|
345
|
+
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`:
|
|
416
346
|
|
|
417
347
|
```tsx title="lib/geistdocs/config.tsx"
|
|
418
348
|
export const config = defineConfig({
|
|
419
349
|
// ...
|
|
420
350
|
pageActions: {
|
|
421
351
|
editSource: false,
|
|
422
|
-
scrollTop: true,
|
|
423
352
|
copyPage: true,
|
|
424
353
|
askAI: true,
|
|
425
|
-
|
|
354
|
+
menu: false,
|
|
355
|
+
openInChat: true,
|
|
426
356
|
},
|
|
427
357
|
feedback: {
|
|
428
358
|
enabled: false,
|
|
@@ -430,6 +360,8 @@ export const config = defineConfig({
|
|
|
430
360
|
});
|
|
431
361
|
```
|
|
432
362
|
|
|
363
|
+
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.
|
|
364
|
+
|
|
433
365
|
`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}`.
|
|
434
366
|
|
|
435
367
|
## Page visibility
|
|
@@ -576,6 +508,25 @@ const docsPage = createDocsPage({
|
|
|
576
508
|
});
|
|
577
509
|
```
|
|
578
510
|
|
|
511
|
+
### Markdown in custom page headers
|
|
512
|
+
|
|
513
|
+
By default, `renderTop` receives the full page Markdown. If the hook only reads page data, opt out of that conversion:
|
|
514
|
+
|
|
515
|
+
```tsx title="app/[lang]/docs/[[...slug]]/page.tsx"
|
|
516
|
+
const docsPage = createDocsPage({
|
|
517
|
+
config,
|
|
518
|
+
source: geistdocsSource,
|
|
519
|
+
renderTopMarkdown: false,
|
|
520
|
+
renderTop: ({ data }) => <MobileDocsBar toc={data.toc} />,
|
|
521
|
+
});
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
`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`.
|
|
525
|
+
|
|
526
|
+
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.
|
|
527
|
+
|
|
528
|
+
### Page URLs and metadata
|
|
529
|
+
|
|
579
530
|
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`.
|
|
580
531
|
|
|
581
532
|
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.
|
|
@@ -11,7 +11,7 @@ related:
|
|
|
11
11
|
|
|
12
12
|
# Edit on GitHub
|
|
13
13
|
|
|
14
|
-
The "Edit on GitHub" feature gives readers a direct link to propose documentation changes. This link appears
|
|
14
|
+
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.
|
|
15
15
|
|
|
16
16
|
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.
|
|
17
17
|
|
package/docs/pages/index.md
CHANGED
|
@@ -25,35 +25,6 @@ Geistdocs has three main parts:
|
|
|
25
25
|
- Local adapter files: The files in your generated project that connect your configuration, content source, routes, and UI customization to the package.
|
|
26
26
|
- Platform services: Hosted endpoints at `geistdocs.com` for optional translation, feedback, and markdown tracking features.
|
|
27
27
|
|
|
28
|
-
```mermaid
|
|
29
|
-
flowchart TB
|
|
30
|
-
subgraph Package["@vercel/geistdocs package"]
|
|
31
|
-
cli["CLI: init, update, translate, search sync"]
|
|
32
|
-
runtime["Runtime: layout, routes, MDX, controls"]
|
|
33
|
-
bundledTemplate["Bundled template snapshot"]
|
|
34
|
-
end
|
|
35
|
-
|
|
36
|
-
subgraph Site["Generated docs site"]
|
|
37
|
-
config["geistdocs.tsx"]
|
|
38
|
-
adapters["app/, components/geistdocs/, lib/geistdocs/"]
|
|
39
|
-
content["content/docs/*.mdx"]
|
|
40
|
-
end
|
|
41
|
-
|
|
42
|
-
subgraph Platform["Geistdocs platform"]
|
|
43
|
-
translate["/translate"]
|
|
44
|
-
feedback["/feedback"]
|
|
45
|
-
tracking["/md-tracking"]
|
|
46
|
-
end
|
|
47
|
-
|
|
48
|
-
cli --> bundledTemplate
|
|
49
|
-
bundledTemplate --> Site
|
|
50
|
-
adapters --> runtime
|
|
51
|
-
content --> adapters
|
|
52
|
-
cli --> translate
|
|
53
|
-
runtime --> feedback
|
|
54
|
-
runtime --> tracking
|
|
55
|
-
```
|
|
56
|
-
|
|
57
28
|
## What you edit
|
|
58
29
|
|
|
59
30
|
Most projects start by editing these files:
|
package/docs/pages/md.md
CHANGED
|
@@ -39,7 +39,7 @@ The `.mdx` version returns:
|
|
|
39
39
|
|
|
40
40
|
For a docs section mounted at `/docs`, the section root remains `/docs.md`. For a source mounted at the app root with `baseUrl: "/"`, Geistdocs uses `/index.md` for the root page. If Next.js has `basePath: "/docs"`, that public root Markdown URL is `/docs/index.md`.
|
|
41
41
|
|
|
42
|
-
Copy Page, View
|
|
42
|
+
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.
|
|
43
43
|
|
|
44
44
|
## Use cases
|
|
45
45
|
|
package/docs/pages/migration.md
CHANGED
|
@@ -119,7 +119,7 @@ Replace imports according to this table:
|
|
|
119
119
|
| `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. |
|
|
120
120
|
| `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. |
|
|
121
121
|
|
|
122
|
-
Keep documentation-specific composites such as `Callout`, `CodeBlock`, `CodeBlockTabs`, `CommandPrompt`,
|
|
122
|
+
Keep documentation-specific composites such as `Callout`, `CodeBlock`, `CodeBlockTabs`, `CommandPrompt`, and `CopyPrompt` imported from `@vercel/geistdocs/components/*`.
|
|
123
123
|
|
|
124
124
|
## Configure Next.js
|
|
125
125
|
|