@vercel/geistdocs 1.26.1 → 1.28.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 (50) hide show
  1. package/dist/changelog.d.ts +36 -0
  2. package/dist/changelog.d.ts.map +1 -0
  3. package/dist/changelog.js +143 -0
  4. package/dist/cli/index.js +1 -1
  5. package/dist/config.d.ts +1 -0
  6. package/dist/config.d.ts.map +1 -1
  7. package/dist/internal/changelog-entries.d.ts +8 -0
  8. package/dist/internal/changelog-entries.d.ts.map +1 -0
  9. package/dist/internal/changelog-entries.js +25 -0
  10. package/dist/internal/changelog-feed.d.ts +10 -0
  11. package/dist/internal/changelog-feed.d.ts.map +1 -0
  12. package/dist/internal/changelog-feed.js +89 -0
  13. package/dist/internal/changelog.d.ts +36 -0
  14. package/dist/internal/changelog.d.ts.map +1 -0
  15. package/dist/internal/changelog.js +98 -0
  16. package/dist/internal/chat/prompt-input.js +1 -1
  17. package/dist/internal/chat/shell.d.ts.map +1 -1
  18. package/dist/internal/chat/shell.js +18 -7
  19. package/dist/internal/provider-client.d.ts.map +1 -1
  20. package/dist/internal/provider-client.js +2 -1
  21. package/dist/internal/webmcp-client.d.ts +6 -0
  22. package/dist/internal/webmcp-client.d.ts.map +1 -0
  23. package/dist/internal/webmcp-client.js +21 -0
  24. package/dist/internal/webmcp.d.ts +30 -0
  25. package/dist/internal/webmcp.d.ts.map +1 -0
  26. package/dist/internal/webmcp.js +102 -0
  27. package/dist/pages/changelog.d.ts +31 -0
  28. package/dist/pages/changelog.d.ts.map +1 -0
  29. package/dist/pages/changelog.js +86 -0
  30. package/dist/proxy.d.ts +3 -1
  31. package/dist/proxy.d.ts.map +1 -1
  32. package/dist/proxy.js +6 -3
  33. package/dist/routes/changelog.d.ts +43 -0
  34. package/dist/routes/changelog.d.ts.map +1 -0
  35. package/dist/routes/changelog.js +81 -0
  36. package/docs/agents.md +3 -1
  37. package/docs/llms.txt +470 -3
  38. package/docs/manifest.json +17 -1
  39. package/docs/pages/ask-ai.md +2 -1
  40. package/docs/pages/changelog.md +385 -0
  41. package/docs/pages/proxy.md +14 -1
  42. package/docs/pages/webmcp.md +58 -0
  43. package/docs/sitemap.md +2 -0
  44. package/package.json +14 -1
  45. package/template/content/docs/ask-ai.mdx +2 -1
  46. package/template/content/docs/changelog.mdx +382 -0
  47. package/template/content/docs/meta.json +2 -0
  48. package/template/content/docs/proxy.mdx +14 -1
  49. package/template/content/docs/webmcp.mdx +54 -0
  50. package/template/package.json +1 -1
package/docs/llms.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Documentation
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 1.26.1.
3
+ These docs are bundled with `@vercel/geistdocs` 1.28.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
@@ -15,6 +15,7 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
15
15
  - [Geistdocs Provider](pages/provider.md): The root provider component that wraps your application to handle toast notifications, search, and analytics.
16
16
  - [Versioned docs](pages/versioned-docs.md): Use createVersionedSources to configure stable, pre-release, or host-based documentation versions.
17
17
  - [Proxy and markdown routes](pages/proxy.md): Configure createProxy with generated route discovery, request hooks, markdown mappings, and a static Next.js matcher.
18
+ - [Add a changelog](pages/changelog.md): Connect collection or paged ChangelogSource data to five thin HTML, Markdown, and JSON adapters, preserving existing docs mappings.
18
19
  - [.md Extension](pages/md.md): Access any documentation page as raw Markdown by appending .md or .mdx to the URL for AI tool consumption.
19
20
  - [Agent readiness](pages/agent-readiness.md): Generate /agents.md and /.well-known/mcp.json from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
20
21
  - [Ask AI](pages/ask-ai.md): An AI-powered chat assistant with context-aware search, persistent history, and suggested prompts for your documentation.
@@ -28,6 +29,7 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
28
29
  - [RSS](pages/rss.md): An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
29
30
  - [Table of contents](pages/table-of-contents.md): Geistdocs builds the "On this page" outline from your headings, indents sub-headings under their parent, and tracks the active section along a straight vertical guide rail.
30
31
  - [Theme-Aware Image](pages/theme-aware-image.md): A component that swaps images based on the active theme, built on top of Next.js Image.
32
+ - [WebMCP](pages/webmcp.md): Expose documentation search and page reading to browser agents.
31
33
 
32
34
  ---
33
35
 
@@ -2320,7 +2322,20 @@ export const config = defineConfig({
2320
2322
  });
2321
2323
  ```
2322
2324
 
2323
- Use `markdownRoutes` when you need to override the inferred mappings:
2325
+ Use `additionalMarkdownRoutes` to add a standalone endpoint, such as a [changelog](/docs/changelog), without replacing docs mappings:
2326
+
2327
+ ```ts title="proxy.ts"
2328
+ const proxy = createProxy({
2329
+ config: geistdocsConfig,
2330
+ additionalMarkdownRoutes: [
2331
+ { from: "/changelog", to: "/[lang]/changelog.md" },
2332
+ ],
2333
+ });
2334
+ ```
2335
+
2336
+ Additional mappings are prepended to inferred or default mappings, or to explicit `markdownRoutes`. The first match wins, so a standalone route takes precedence over a root `/*path` catch-all. Keep mapping paths app-local and install the destination Route Handler separately.
2337
+
2338
+ Use `markdownRoutes` when you need to replace the inferred mappings:
2324
2339
 
2325
2340
  ```ts title="proxy.ts"
2326
2341
  const proxy = createProxy({
@@ -2436,6 +2451,395 @@ Both `before` and `after` receive the same context:
2436
2451
  - Read [Versioned docs](/docs/versioned-docs) to map multiple public route families.
2437
2452
 
2438
2453
 
2454
+ ---
2455
+
2456
+ ---
2457
+ title: Add a changelog
2458
+ description: Add a paginated changelog from Changesets, a CMS, or an API, with Show more, numbered archives, and Markdown output.
2459
+ type: guide
2460
+ summary: Connect collection or paged ChangelogSource data to five thin HTML, Markdown, and JSON adapters, preserving existing docs mappings.
2461
+ url: /docs/changelog
2462
+ source: apps/template/content/docs/changelog.mdx
2463
+ prerequisites:
2464
+ - /docs/configuration
2465
+ related:
2466
+ - /docs/proxy
2467
+ - /docs/agent-readiness
2468
+ ---
2469
+
2470
+ # Add a changelog
2471
+
2472
+ Publish release notes in batches with **Show more**, numbered archive pages, and matching Markdown output. Geistdocs provides the page UI; your app owns the source, caching, and route adapters.
2473
+
2474
+ In the Geistdocs repository, `/changelog` reads the package's released `CHANGELOG.md` with 10 entries per page. The standalone `apps/example-basic` app uses one entry per page to demonstrate pagination in English and Chinese. These examples are not enabled in newly scaffolded sites. The template's `(changelog)` route group and repo-only proxy mappings are excluded from the scaffold bundle.
2475
+
2476
+ ## How consumers connect a changelog
2477
+
2478
+ Your app chooses where release data comes from. Geistdocs validates the entries and renders the shared page design, metadata, and Markdown output.
2479
+
2480
+ 1. Create a server-side source that returns a collection or a requested page of releases, newest first.
2481
+ 2. Share the source, paths, and `pageSize` across the route factories.
2482
+ 3. Add the five thin adapters below for root HTML, numbered HTML, root Markdown, numbered Markdown, and JSON data.
2483
+ 4. Add Markdown proxy mappings and a navigation link.
2484
+
2485
+ Adding the page is the opt-in. There is no global enable flag, and the package does not create App Router files in an existing site.
2486
+
2487
+ ## Read a Changesets changelog
2488
+
2489
+ Use `createChangesetsChangelogSource` from `@vercel/geistdocs/changelog` to read the durable `CHANGELOG.md` produced by Changesets. It does not read pending `.changeset/*.md` files or run the release process.
2490
+
2491
+ Create a server-side file that shares the source and options across all five adapters:
2492
+
2493
+ ```ts title="lib/geistdocs/changelog.ts"
2494
+ import { readFile } from "node:fs/promises";
2495
+ import path from "node:path";
2496
+ import { createChangesetsChangelogSource } from "@vercel/geistdocs/changelog";
2497
+ import { config } from "@/lib/geistdocs/config";
2498
+
2499
+ const readChangelog = async () => {
2500
+ "use cache";
2501
+
2502
+ return await readFile(path.join(process.cwd(), "CHANGELOG.md"), "utf8");
2503
+ };
2504
+
2505
+ export const changelogOptions = {
2506
+ config,
2507
+ source: createChangesetsChangelogSource({ read: readChangelog }),
2508
+ path: "/changelog",
2509
+ markdownPath: "/changelog.md",
2510
+ pageSize: 10,
2511
+ title: "Changelog",
2512
+ description: "The latest releases, improvements, and fixes.",
2513
+ };
2514
+ ```
2515
+
2516
+ This path assumes `CHANGELOG.md` is in the app root, where `process.cwd()` points when Next.js runs. Use a known, statically analyzable path so deployment file tracing can include the file. For a monorepo file outside the app root, use the correct relative path and configure deployment tracing bounds, including `outputFileTracingRoot`, if the deployed server needs to read it at runtime. A cache miss or refresh can still require the file.
2517
+
2518
+ The reader accepts a string or a promise of a string. The adapter recognizes level-two semantic version headings such as `## 1.2.0`, preserves file order and release Markdown, and skips `## Unreleased`. It returns version-only entries, which display as `v1.2.0`. The version becomes the entry ID, with `+` replaced by `_` for safe anchors. Changesets entries have no publication date; Geistdocs does not infer dates from Git history or file timestamps.
2519
+
2520
+ ## Add the HTML page
2521
+
2522
+ Use the template's `getRootLang` helper with Cache Components:
2523
+
2524
+ ```tsx title="app/[lang]/changelog/page.tsx"
2525
+ import { createChangelogPage } from "@vercel/geistdocs/pages/changelog";
2526
+ import { changelogOptions } from "@/lib/geistdocs/changelog";
2527
+ import { getRootLang } from "@/lib/geistdocs/root-params";
2528
+
2529
+ const changelogPage = createChangelogPage({
2530
+ ...changelogOptions,
2531
+ getLang: getRootLang,
2532
+ });
2533
+
2534
+ export const generateMetadata = changelogPage.generateMetadata;
2535
+ export const generateStaticParams = changelogPage.generateStaticParams;
2536
+ export default changelogPage.Page;
2537
+ ```
2538
+
2539
+ 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.
2540
+
2541
+ `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.
2542
+
2543
+ 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.
2544
+
2545
+ ## Add numbered HTML pages
2546
+
2547
+ Use the same factory's archive exports for `/changelog/page/2` and later pages:
2548
+
2549
+ ```tsx title="app/[lang]/changelog/page/[page]/page.tsx"
2550
+ import { createChangelogPage } from "@vercel/geistdocs/pages/changelog";
2551
+ import { changelogOptions } from "@/lib/geistdocs/changelog";
2552
+ import { getRootLang } from "@/lib/geistdocs/root-params";
2553
+
2554
+ const changelogPage = createChangelogPage({
2555
+ ...changelogOptions,
2556
+ getLang: getRootLang,
2557
+ });
2558
+
2559
+ export const generateMetadata = changelogPage.generatePaginatedMetadata;
2560
+ export const generateStaticParams = changelogPage.generatePageParams;
2561
+ export default changelogPage.PaginatedPage;
2562
+ ```
2563
+
2564
+ `PaginatedPage` renders only the requested batch, with **Show more** for older releases and **Newer releases** for the previous page. Archive metadata uses the numbered HTML canonical URL and its `.md` alternate. `/changelog/page/1` redirects to `/changelog`.
2565
+
2566
+ ## Add the optional Markdown route
2567
+
2568
+ Reuse the shared options for the root Markdown endpoint:
2569
+
2570
+ ```ts title="app/[lang]/changelog.md/route.ts"
2571
+ import { createChangelogMarkdownRoute } from "@vercel/geistdocs/routes/changelog";
2572
+ import { changelogOptions } from "@/lib/geistdocs/changelog";
2573
+
2574
+ const changelogRoute = createChangelogMarkdownRoute(changelogOptions);
2575
+
2576
+ export const GET = changelogRoute.GET;
2577
+ export const generateStaticParams = changelogRoute.generateStaticParams;
2578
+ ```
2579
+
2580
+ The root route returns the first batch with anchor IDs and a **Next** Markdown link when older releases exist. Its HTTP `Link` header points to the root HTML canonical URL. `path` still identifies the HTML page, not the Markdown endpoint. Route Handlers use context `params` to resolve the language.
2581
+
2582
+ Add the numbered Markdown handler as a sibling route. The same `GET` reads the optional `params.page`:
2583
+
2584
+ ```ts title="app/[lang]/changelog-pages.mdx/[page]/route.ts"
2585
+ import { createChangelogMarkdownRoute } from "@vercel/geistdocs/routes/changelog";
2586
+ import { changelogOptions } from "@/lib/geistdocs/changelog";
2587
+
2588
+ const changelogRoute = createChangelogMarkdownRoute(changelogOptions);
2589
+
2590
+ export const GET = changelogRoute.GET;
2591
+ export const generateStaticParams = changelogRoute.generatePageParams;
2592
+ ```
2593
+
2594
+ The proxy maps `/changelog/page/2.md` to `/[lang]/changelog-pages.mdx/2` internally. This handler serves the second batch with **Previous** and, when applicable, **Next** links. Its canonical `Link` header points to `/changelog/page/2`, not the internal handler path.
2595
+
2596
+ Add this mapping to your existing `createProxy` options, preserving its hooks, tracking, and static matcher:
2597
+
2598
+ ```ts title="proxy.ts"
2599
+ import { createProxy } from "@vercel/geistdocs/proxy";
2600
+ import { config as geistdocsConfig } from "@/lib/geistdocs/config";
2601
+
2602
+ const proxy = createProxy({
2603
+ config: geistdocsConfig,
2604
+ additionalMarkdownRoutes: [
2605
+ {
2606
+ from: "/changelog/page/*path",
2607
+ to: "/[lang]/changelog-pages.mdx/*path",
2608
+ },
2609
+ { from: "/changelog", to: "/[lang]/changelog.md" },
2610
+ ],
2611
+ });
2612
+
2613
+ export const config = {
2614
+ matcher: [
2615
+ "/((?!api(?:/|$)|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
2616
+ ],
2617
+ };
2618
+
2619
+ export default proxy;
2620
+ ```
2621
+
2622
+ `additionalMarkdownRoutes` is prepended to inferred or default docs mappings, or to explicit `markdownRoutes`. The changelog mapping therefore wins before a root `/*path` catch-all without removing docs negotiation. Explicit `markdownRoutes` still replaces inferred mappings. Keep mapping paths app-local and use `[lang]` in the destination.
2623
+
2624
+ Put the numbered mapping before the root mapping. These mappings enable `.md`, `.mdx`, `Accept: text/markdown`, and detected-agent requests for root and numbered pages, including localized paths such as `/cn/changelog/page/2.md`. Restart `next dev` after adding routes so the app-route manifest is regenerated.
2625
+
2626
+ ## Add the Show more data handler
2627
+
2628
+ **Show more** requires a JSON route that serves the next batch using the same source and `pageSize`:
2629
+
2630
+ ```ts title="app/[lang]/changelog/data/[page]/route.ts"
2631
+ import { createChangelogDataRoute } from "@vercel/geistdocs/routes/changelog";
2632
+ import { changelogOptions } from "@/lib/geistdocs/changelog";
2633
+
2634
+ const changelogRoute = createChangelogDataRoute(changelogOptions);
2635
+
2636
+ export const GET = changelogRoute.GET;
2637
+ export const generateStaticParams = changelogRoute.generateStaticParams;
2638
+ ```
2639
+
2640
+ The default `dataPath` is `${path}/data`, so this setup fetches `/changelog/data/2` on the first **Show more** activation. To use another endpoint, set `dataPath` in the shared options and place this handler at the matching route. Configuring `dataPath` alone does not create a handler.
2641
+
2642
+ The root is pre-rendered with only the first 10 entries by default. The browser receives one batch initially, not the entire history. With JavaScript, **Show more** fetches and appends the next JSON batch without navigating. It shows a loading state and allows retry after a failed request. Without JavaScript, the same normal `href` opens the next numbered HTML page. Readers can also open the link in another tab.
2643
+
2644
+ ## Use a custom source
2645
+
2646
+ Replace the Changesets source with an object implementing either form of `ChangelogSource`. A source can read local files, a CMS, a database, GitHub releases, or an HTTP API. `getEntries` is a convenience for a full collection; use `getPage` for a provider that fetches one batch at a time. Keep the shared options and route adapters unchanged:
2647
+
2648
+ ```ts title="lib/geistdocs/changelog.ts"
2649
+ import type {
2650
+ ChangelogEntry,
2651
+ ChangelogSource,
2652
+ } from "@vercel/geistdocs/changelog";
2653
+ import { config } from "@/lib/geistdocs/config";
2654
+
2655
+ // biome-ignore lint/suspicious/useAwait: Cache Components requires an async reader, including for this local data.
2656
+ const readEntries = async (lang: string): Promise<ChangelogEntry[]> => {
2657
+ "use cache";
2658
+
2659
+ return [
2660
+ {
2661
+ id: "1.2.0",
2662
+ title: lang === "cn" ? "保存搜索筛选条件" : "Saved search filters",
2663
+ body: lang === "cn"
2664
+ ? "保存**搜索筛选条件**,下次访问时继续使用。"
2665
+ : "Save **search filters** for your next visit.",
2666
+ version: "1.2.0",
2667
+ publishedAt: "2026-09-08",
2668
+ },
2669
+ ];
2670
+ };
2671
+
2672
+ const source: ChangelogSource = {
2673
+ getEntries: ({ lang }) => readEntries(lang),
2674
+ };
2675
+
2676
+ export const changelogOptions = {
2677
+ config,
2678
+ source,
2679
+ path: "/changelog",
2680
+ markdownPath: "/changelog.md",
2681
+ pageSize: 10,
2682
+ title: "Changelog",
2683
+ description: "Updates to search and navigation.",
2684
+ };
2685
+ ```
2686
+
2687
+ `getEntries({ lang })` accepts a configured language and returns `ChangelogEntry[]` or a promise of that array. Geistdocs reads and validates the full collection on the server, then selects the requested batch. Only that batch reaches the browser. The source owns translation and fallback policy; this example falls back to English. The Changesets adapter serves the same file for every locale. Unsupported route locales return not found.
2688
+
2689
+ Keep asynchronous data access in an app-owned `"use cache"` reader with `cacheComponents: true`. Do not add `dynamic`, `revalidate`, or `fetchCache` route exports. Keep source getters and credentials in server-side modules, not the shared `geistdocs.tsx` config, which is available to client components.
2690
+
2691
+ Each entry follows these constraints:
2692
+
2693
+ | Field | Requirement |
2694
+ | --- | --- |
2695
+ | `id` | Stable, unique within the source result, and starts with an ASCII letter or digit. Remaining characters can be ASCII letters, digits, `.`, `_`, or `-`. Reuse IDs across translations to preserve release links. |
2696
+ | `title` | Optional text, preferred over `version`. Required when `version` is omitted. A blank title falls back to a provided version. |
2697
+ | `body` | Markdown text, not executable MDX. The UI supports GitHub Flavored Markdown and disables raw HTML. |
2698
+ | `version` | Optional nonempty text. Required when `title` is omitted or blank. |
2699
+ | `publishedAt` | Optional valid ISO date (`2026-09-08`) or timestamp with a timezone. Omit unknown dates. |
2700
+
2701
+ Return entries newest first. Geistdocs preserves source order without sorting by date or version. Return `[]` when there are no releases; the page shows `No releases published yet.`, and Markdown contains only the page heading and configured description. Source failures and invalid entries propagate as errors rather than appearing as an empty changelog. An empty or title-only Changesets file returns no releases; unrecognized release content throws.
2702
+
2703
+ ## Choose a title or version
2704
+
2705
+ Provide a title, a version, or both. When both are present, only the title appears as the release heading. Without a title, the heading uses the version with a `v` prefix; an existing `v` is not duplicated. HTML and Markdown use the same label.
2706
+
2707
+ ```ts title="Release entry examples"
2708
+ import type { ChangelogEntry } from "@vercel/geistdocs/changelog";
2709
+
2710
+ const entries = [
2711
+ {
2712
+ id: "saved-filters",
2713
+ title: "Saved search filters",
2714
+ version: "1.2.0",
2715
+ body: "Save **search filters** for your next visit.",
2716
+ publishedAt: "2026-09-08",
2717
+ },
2718
+ {
2719
+ id: "keyboard-navigation",
2720
+ title: "Keyboard navigation improvements",
2721
+ body: "Closing search returns focus to the search button.",
2722
+ publishedAt: "2026-09-04",
2723
+ },
2724
+ {
2725
+ id: "1.1.1",
2726
+ version: "1.1.1",
2727
+ body: "Fix navigation to nested documentation pages.",
2728
+ },
2729
+ ] satisfies ChangelogEntry[];
2730
+ ```
2731
+
2732
+ These headings are `Saved search filters`, `Keyboard navigation improvements`, and `v1.1.1`. TypeScript requires at least one of `title` or `version`, and runtime validation rejects entries where neither provides a label.
2733
+
2734
+ The release heading is also its permalink. Entries rendered on the current page use `#id`; an entry appended from page 2 links to `/changelog/page/2#id`, so reloading the link renders that batch. IDs remain stable when titles change, but numbered page membership can move as releases are published. These links are not permanent per-version URLs across publishing. A separate version badge or permalink button is not rendered.
2735
+
2736
+ ## Clean Changesets release notes
2737
+
2738
+ The Changesets adapter removes bare generated commit prefixes, such as `f31d616:`, from Major, Minor, and Patch Changes lists. Existing PR and commit links, code examples, and authored prose remain intact. The HTML page, JSON batches, and Markdown routes use the same cleaned notes.
2739
+
2740
+ ## Display publication dates
2741
+
2742
+ Set `publishedAt` when the source provides an authoritative publication date. Dates appear alongside entries on desktop and above their headings on mobile. Timestamps are formatted in UTC; date-only values retain their calendar date. Entries without a date omit it, and a wholly undated changelog has no date column.
2743
+
2744
+ To add dates to Changesets entries, wrap the Changesets source in your own `getEntries` implementation and join publication dates by version. For example, a consumer could combine local `CHANGELOG.md` bodies with GitHub release publication metadata. Omit dates that cannot be matched reliably.
2745
+
2746
+ ## Read entries from an HTTP API
2747
+
2748
+ For a paged API, implement `getPage({ lang, page, pageSize })` and return `{ entries, total }` or a promise of that object. Geistdocs requests only the needed batch, without downloading earlier pages. `total` must be the exact number of releases matching the locale and any source filters, not an estimate or the current batch length.
2749
+
2750
+ Set the server-only `CHANGELOG_API_URL` environment variable to the endpoint. Set `CHANGELOG_API_TOKEN` if it requires a bearer token. This example validates an API response matching the paged source contract:
2751
+
2752
+ ```ts title="lib/geistdocs/changelog.ts"
2753
+ import {
2754
+ type ChangelogSource,
2755
+ validateChangelogEntries,
2756
+ } from "@vercel/geistdocs/changelog";
2757
+ import { config } from "@/lib/geistdocs/config";
2758
+
2759
+ const readPage = async (lang: string, page: number, pageSize: number) => {
2760
+ "use cache";
2761
+
2762
+ const endpoint = process.env.CHANGELOG_API_URL;
2763
+ if (!endpoint) {
2764
+ throw new Error("Set CHANGELOG_API_URL to your release notes endpoint.");
2765
+ }
2766
+
2767
+ const url = new URL(endpoint);
2768
+ url.searchParams.set("lang", lang);
2769
+ url.searchParams.set("page", String(page));
2770
+ url.searchParams.set("pageSize", String(pageSize));
2771
+ const token = process.env.CHANGELOG_API_TOKEN;
2772
+ const response = await fetch(url, {
2773
+ headers: token ? { Authorization: `Bearer ${token}` } : undefined,
2774
+ });
2775
+ if (!response.ok) {
2776
+ throw new Error(`Release notes request failed: ${response.status}`);
2777
+ }
2778
+
2779
+ const result: unknown = await response.json();
2780
+ if (
2781
+ !result ||
2782
+ typeof result !== "object" ||
2783
+ !("entries" in result) ||
2784
+ !Array.isArray(result.entries) ||
2785
+ !("total" in result) ||
2786
+ typeof result.total !== "number" ||
2787
+ !Number.isSafeInteger(result.total) ||
2788
+ result.total < 0
2789
+ ) {
2790
+ throw new Error("Invalid release page response.");
2791
+ }
2792
+
2793
+ const entries = validateChangelogEntries(result.entries);
2794
+ const remaining = Math.max(0, result.total - (page - 1) * pageSize);
2795
+ if (entries.length !== Math.min(pageSize, remaining)) {
2796
+ throw new Error("Release page length does not match its total.");
2797
+ }
2798
+ return { entries, total: result.total };
2799
+ };
2800
+
2801
+ const source: ChangelogSource = {
2802
+ getPage: ({ lang, page, pageSize }) => readPage(lang, page, pageSize),
2803
+ };
2804
+
2805
+ export const changelogOptions = {
2806
+ config,
2807
+ source,
2808
+ path: "/changelog",
2809
+ markdownPath: "/changelog.md",
2810
+ pageSize: 10,
2811
+ title: "Changelog",
2812
+ description: "The latest releases, improvements, and fixes.",
2813
+ };
2814
+ ```
2815
+
2816
+ The query parameters are an example API convention, not a Geistdocs requirement. Adapt the request and response mapping to your provider. Each in-range page must contain exactly `Math.min(pageSize, total - (page - 1) * pageSize)` entries. Return `{ entries: [], total: 0 }` for an empty history. Use a consistent newest-first order across pages, with unique IDs across the history.
2817
+
2818
+ Consumers choose the source and cache policy. This cached reader keys data by locale, page, and page size; configure cache lifetime or invalidation to match your publishing workflow. Only normalized release data reaches the public HTML and JSON endpoints. Keep credentials in server-side modules, not entry bodies or client-visible configuration.
2819
+
2820
+ ## Make the changelog discoverable
2821
+
2822
+ Add `{ label: "Changelog", href: "/changelog" }` to `nav` in `geistdocs.tsx`. For agent discovery, you can also add a resource link through [`agent.links`](/docs/agent-readiness).
2823
+
2824
+ Standalone changelog entries are not automatically included in docs search, `/llms.txt`, or sitemaps. The Markdown endpoint and discovery links expose the changelog separately from the documentation corpus.
2825
+
2826
+ ## Configure archive generation and errors
2827
+
2828
+ The HTML and Markdown factories expose `generatePageParams` for numbered archives. Export it as Next.js `generateStaticParams` to prebuild archive pages, as shown above. It reads page 1's total for each configured locale to generate `{ lang, page }` values starting at page 2. Rendering those archives then reads their respective batches. Prebuilding is optional; consumers can choose on-demand archive rendering instead. The data factory's `generateStaticParams` also includes page 1.
2829
+
2830
+ Page parameters are positive decimal integers without leading zeroes. Invalid values such as `0`, `02`, or `abc`, unsupported locales, and pages beyond the total return not found. Markdown and JSON handlers return HTTP `404`; HTML uses Next.js not-found handling. Source failures, invalid totals, invalid entries, and mismatched in-range batch lengths propagate as errors rather than appearing as empty releases or a missing page.
2831
+
2832
+ Individual release routes and a changelog RSS feed are not included.
2833
+
2834
+ ## Check the routes locally
2835
+
2836
+ Open the template's `/changelog` and confirm it initially renders 10 entries. Select **Show more** and confirm it renders 20 entries without leaving the page. Reload a newly appended entry's title link and confirm the entry appears on its numbered archive.
2837
+
2838
+ Open `/changelog/page/2` and `/changelog/page/2.md`. Both should contain only the second batch; HTML metadata and the Markdown canonical `Link` header should identify `/changelog/page/2`. Root `/changelog.md` should contain only the first batch and a **Next** link, while the second Markdown page has **Previous** and **Next** links when applicable. Disable JavaScript and confirm **Show more** navigates to page 2.
2839
+
2840
+ The basic example uses `pageSize: 1`, so its root shows the custom title and **Show more** appends `v1.1.1`. Repeat these checks under `/cn/changelog` for Chinese body text and localized canonical URLs. `/docs/changelog` remains the separate setup guide, and existing `/docs` Markdown negotiation should continue to work.
2841
+
2842
+
2439
2843
  ---
2440
2844
 
2441
2845
  ---
@@ -2760,6 +3164,7 @@ Users can open the chat interface at any time by:
2760
3164
  Once open, users can:
2761
3165
 
2762
3166
  - Ask questions about any part of your documentation
3167
+ - Expand the desktop panel to a full-screen view for wide responses and code blocks
2763
3168
  - Upload files or images for context
2764
3169
  - View AI-powered search results from your docs
2765
3170
  - Get step-by-step guidance on complex topics
@@ -2916,7 +3321,7 @@ Conversations are automatically saved to the browser's IndexedDB, providing:
2916
3321
 
2917
3322
  The chat interface adapts to different screen sizes:
2918
3323
 
2919
- - **Desktop**: Slides in from the right side as a sidebar panel
3324
+ - **Desktop**: Slides in from the right side as a sidebar panel. Use **Expand chat** in the panel header to switch to a full-screen view, and **Collapse chat** or `Escape` to return to the sidebar.
2920
3325
  - **Mobile**: Opens as a bottom drawer.
2921
3326
 
2922
3327
  ## Configuration
@@ -4021,3 +4426,65 @@ Because this component relies on client-side theme detection, it is a client com
4021
4426
  | `height` | `number` | The height of the image in pixels |
4022
4427
  | `...rest` | `ImageProps` | Any additional props supported by the Next.js `Image` component |
4023
4428
 
4429
+
4430
+ ---
4431
+
4432
+ ---
4433
+ title: WebMCP
4434
+ description: Expose documentation search and page reading to browser agents.
4435
+ url: /docs/webmcp
4436
+ source: apps/template/content/docs/webmcp.mdx
4437
+ ---
4438
+
4439
+ # WebMCP
4440
+
4441
+ Geistdocs includes experimental WebMCP support. WebMCP is disabled by default. To opt in, add it to the `defineConfig` call in `lib/geistdocs/config.tsx`:
4442
+
4443
+ ```ts
4444
+ export const config = defineConfig({
4445
+ // ...
4446
+ webmcp: { enabled: true },
4447
+ });
4448
+ ```
4449
+
4450
+ The provider exposes two read-only tools:
4451
+
4452
+ | Tool | Input | Result |
4453
+ | --- | --- | --- |
4454
+ | `search_docs` | `query`, a nonempty string up to 500 characters | Results from the existing search API in the current language |
4455
+ | `read_current_page` | None | The current documentation page as Markdown |
4456
+
4457
+ Search respects the existing search visibility rules. Page reading uses the existing Markdown route and fails if the current page does not serve Markdown. Neither tool sends data to an external model or modifies documentation. Returned documentation is marked as untrusted content.
4458
+
4459
+ WebMCP requires a compatible browser with the experimental API enabled. Unsupported browsers continue to work normally. This feature uses browser-local tools, independently of the site's remote MCP discovery manifest.
4460
+
4461
+ ## Verify locally
4462
+
4463
+ Enable WebMCP testing as described in the [Chrome documentation](https://developer.chrome.com/docs/ai/webmcp). Open a documentation page and inspect its tools:
4464
+
4465
+ ```js
4466
+ const tools = await document.modelContext.getTools();
4467
+ const search = tools.find((tool) => tool.name === "search_docs");
4468
+ await document.modelContext.executeTool(search, JSON.stringify({ query: "configuration" }));
4469
+ const read = tools.find((tool) => tool.name === "read_current_page");
4470
+ await document.modelContext.executeTool(read, "{}");
4471
+ ```
4472
+
4473
+ Navigate to another documentation page and read it again. Repeat in a translated route and, when configured, under the site's base path. Disable the feature and verify the provider removes its tools.
4474
+
4475
+ ## agent-browser
4476
+
4477
+ With agent-browser 0.36.0 or newer, WebMCP is enabled by default in managed Chrome sessions:
4478
+
4479
+ ```bash
4480
+ agent-browser --session docs-check open http://localhost:3000/docs
4481
+ agent-browser --session docs-check webmcp list
4482
+ agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration"}'
4483
+ agent-browser --session docs-check webmcp invoke read_current_page --params '{}'
4484
+ agent-browser --session docs-check close
4485
+ ```
4486
+
4487
+ Discovery includes each tool's origin, frame, schema, and read-only annotations. Check the invocation's `status`: a successfully delivered command can still contain a failed tool execution.
4488
+
4489
+ Both tools limit network requests to 15 seconds. When the browser supplies an execution signal, cancellation also aborts the request. Some experimental browser versions, including Chrome 152, omit that signal: canceling an invocation in those versions does not immediately abort its underlying fetch, which remains bounded by the request deadline.
4490
+
@@ -98,6 +98,15 @@
98
98
  "type": "reference",
99
99
  "url": "/docs/proxy"
100
100
  },
101
+ {
102
+ "description": "Add a paginated changelog from Changesets, a CMS, or an API, with Show more, numbered archives, and Markdown output.",
103
+ "path": "pages/changelog.md",
104
+ "source": "apps/template/content/docs/changelog.mdx",
105
+ "summary": "Connect collection or paged ChangelogSource data to five thin HTML, Markdown, and JSON adapters, preserving existing docs mappings.",
106
+ "title": "Add a changelog",
107
+ "type": "guide",
108
+ "url": "/docs/changelog"
109
+ },
101
110
  {
102
111
  "description": "Access documentation pages as raw Markdown by appending .md or .mdx to any URL",
103
112
  "path": "pages/md.md",
@@ -214,8 +223,15 @@
214
223
  "title": "Theme-Aware Image",
215
224
  "type": "reference",
216
225
  "url": "/docs/theme-aware-image"
226
+ },
227
+ {
228
+ "description": "Expose documentation search and page reading to browser agents.",
229
+ "path": "pages/webmcp.md",
230
+ "source": "apps/template/content/docs/webmcp.mdx",
231
+ "title": "WebMCP",
232
+ "url": "/docs/webmcp"
217
233
  }
218
234
  ],
219
235
  "source": "apps/template/content/docs",
220
- "version": "1.26.1"
236
+ "version": "1.28.0"
221
237
  }
@@ -42,6 +42,7 @@ Users can open the chat interface at any time by:
42
42
  Once open, users can:
43
43
 
44
44
  - Ask questions about any part of your documentation
45
+ - Expand the desktop panel to a full-screen view for wide responses and code blocks
45
46
  - Upload files or images for context
46
47
  - View AI-powered search results from your docs
47
48
  - Get step-by-step guidance on complex topics
@@ -198,7 +199,7 @@ Conversations are automatically saved to the browser's IndexedDB, providing:
198
199
 
199
200
  The chat interface adapts to different screen sizes:
200
201
 
201
- - **Desktop**: Slides in from the right side as a sidebar panel
202
+ - **Desktop**: Slides in from the right side as a sidebar panel. Use **Expand chat** in the panel header to switch to a full-screen view, and **Collapse chat** or `Escape` to return to the sidebar.
202
203
  - **Mobile**: Opens as a bottom drawer.
203
204
 
204
205
  ## Configuration