@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.
Files changed (74) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +12 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/internal/lazy-mdx-components.d.ts +0 -2
  5. package/dist/internal/lazy-mdx-components.d.ts.map +1 -1
  6. package/dist/internal/lazy-mdx-components.js +0 -1
  7. package/dist/internal/mermaid-source.d.ts +5 -0
  8. package/dist/internal/mermaid-source.d.ts.map +1 -0
  9. package/dist/internal/mermaid-source.js +5 -0
  10. package/dist/internal/page-action-options.d.ts +9 -4
  11. package/dist/internal/page-action-options.d.ts.map +1 -1
  12. package/dist/internal/page-action-options.js +19 -12
  13. package/dist/internal/page-actions-client.d.ts.map +1 -1
  14. package/dist/internal/page-actions-client.js +19 -112
  15. package/dist/internal/page-actions-gate.d.ts +6 -0
  16. package/dist/internal/page-actions-gate.d.ts.map +1 -1
  17. package/dist/internal/page-actions-gate.js +11 -9
  18. package/dist/internal/page-actions-menu-client.d.ts +8 -0
  19. package/dist/internal/page-actions-menu-client.d.ts.map +1 -0
  20. package/dist/internal/page-actions-menu-client.js +105 -0
  21. package/dist/internal/page-markdown.d.ts +3 -0
  22. package/dist/internal/page-markdown.d.ts.map +1 -0
  23. package/dist/internal/page-markdown.js +45 -0
  24. package/dist/internal/toc-actions-client.d.ts +3 -1
  25. package/dist/internal/toc-actions-client.d.ts.map +1 -1
  26. package/dist/internal/toc-actions-client.js +7 -9
  27. package/dist/mdx.js +3 -2
  28. package/dist/next.d.ts +2 -15
  29. package/dist/next.d.ts.map +1 -1
  30. package/dist/next.js +5 -27
  31. package/dist/pages/docs.d.ts +6 -1
  32. package/dist/pages/docs.d.ts.map +1 -1
  33. package/dist/pages/docs.js +11 -6
  34. package/dist/routes/search.d.ts +1 -8
  35. package/dist/routes/search.d.ts.map +1 -1
  36. package/dist/routes/search.js +82 -120
  37. package/dist/source-config.d.ts +0 -2
  38. package/dist/source-config.d.ts.map +1 -1
  39. package/dist/source-config.js +0 -2
  40. package/docs/agents.md +2 -3
  41. package/docs/llms.txt +31 -250
  42. package/docs/manifest.json +2 -11
  43. package/docs/pages/changelog.md +1 -1
  44. package/docs/pages/components/index.md +0 -1
  45. package/docs/pages/configuration.md +24 -73
  46. package/docs/pages/edit-on-github.md +1 -1
  47. package/docs/pages/index.md +0 -29
  48. package/docs/pages/md.md +1 -1
  49. package/docs/pages/migration.md +1 -1
  50. package/docs/pages/syntax.md +1 -107
  51. package/docs/sitemap.md +1 -2
  52. package/package.json +14 -14
  53. package/source-config.js +0 -2
  54. package/template/AGENTS.md +0 -4
  55. package/template/app/[lang]/docs/[[...slug]]/page.tsx +1 -0
  56. package/template/app/api/search/route.ts +2 -7
  57. package/template/content/docs/changelog.mdx +1 -1
  58. package/template/content/docs/components/index.mdx +0 -1
  59. package/template/content/docs/components/meta.json +0 -1
  60. package/template/content/docs/configuration.mdx +24 -73
  61. package/template/content/docs/edit-on-github.mdx +1 -1
  62. package/template/content/docs/index.mdx +0 -28
  63. package/template/content/docs/md.mdx +1 -1
  64. package/template/content/docs/migration.mdx +1 -1
  65. package/template/content/docs/syntax.cn.mdx +1 -107
  66. package/template/content/docs/syntax.mdx +1 -107
  67. package/template/next.config.ts +1 -1
  68. package/template/package.json +1 -2
  69. package/template/source.config.ts +1 -1
  70. package/docs/pages/components/mermaid.md +0 -29
  71. package/search-index.d.ts +0 -14
  72. package/search-index.js +0 -447
  73. package/template/content/docs/components/mermaid.mdx +0 -25
  74. 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` 2.16.0-canary.abbda54.
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, and Mermaid diagrams.
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`, `CopyPrompt`, and `Mermaid` imported from `@vercel/geistdocs/components/*`.
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
- Content actions appear in the **Copy page** menu beside the page title. **Scroll to top** and **Give feedback** remain below the table of contents so they stay available while you read. These actions are enabled by default and can be disabled through `defineConfig` in `lib/geistdocs/config.tsx`:
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
- openInChat: false,
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, and Mermaid diagrams.
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, including **View as Markdown**, 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.
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 as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. View as Markdown 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.
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 in the table of contents sidebar on every documentation page.
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
  ---
@@ -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, and Mermaid diagrams.",
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": "2.16.0-canary.abbda54"
461
+ "version": "3.0.0"
471
462
  }
@@ -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, including **View as Markdown**, 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.
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
- Content actions appear in the **Copy page** menu beside the page title. **Scroll to top** and **Give feedback** remain below the table of contents so they stay available while you read. These actions are enabled by default and can be disabled through `defineConfig` in `lib/geistdocs/config.tsx`:
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
- openInChat: false,
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 in the table of contents sidebar on every documentation page.
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
 
@@ -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 as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. View as Markdown 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.
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
 
@@ -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`, `CopyPrompt`, and `Mermaid` imported from `@vercel/geistdocs/components/*`.
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