@vercel/geistdocs 1.12.0 → 1.14.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 (103) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/config.js +35 -0
  5. package/dist/controls.d.ts.map +1 -1
  6. package/dist/controls.js +7 -5
  7. package/dist/footer.d.ts +1 -1
  8. package/dist/footer.d.ts.map +1 -1
  9. package/dist/footer.js +1 -1
  10. package/dist/home-layout.d.ts.map +1 -1
  11. package/dist/home-layout.js +2 -7
  12. package/dist/internal/chat/shell.d.ts.map +1 -1
  13. package/dist/internal/chat/shell.js +2 -1
  14. package/dist/internal/footer/rss-button.d.ts +3 -1
  15. package/dist/internal/footer/rss-button.d.ts.map +1 -1
  16. package/dist/internal/footer/rss-button.js +2 -1
  17. package/dist/internal/localized-link.d.ts.map +1 -1
  18. package/dist/internal/localized-link.js +9 -4
  19. package/dist/internal/page-actions-client.d.ts +1 -0
  20. package/dist/internal/page-actions-client.d.ts.map +1 -1
  21. package/dist/internal/page-actions-client.js +2 -4
  22. package/dist/internal/provider-client.d.ts.map +1 -1
  23. package/dist/internal/provider-client.js +1 -1
  24. package/dist/internal/search.d.ts.map +1 -1
  25. package/dist/internal/search.js +2 -1
  26. package/dist/internal/sidebar-responsive.d.ts +3 -0
  27. package/dist/internal/sidebar-responsive.d.ts.map +1 -0
  28. package/dist/internal/sidebar-responsive.js +10 -0
  29. package/dist/internal/sidebar-tree.d.ts +23 -0
  30. package/dist/internal/sidebar-tree.d.ts.map +1 -0
  31. package/dist/internal/sidebar-tree.js +115 -0
  32. package/dist/internal/sidebar.d.ts +2 -5
  33. package/dist/internal/sidebar.d.ts.map +1 -1
  34. package/dist/internal/sidebar.js +282 -44
  35. package/dist/internal/table-of-contents.js +1 -1
  36. package/dist/internal/ui/sheet.d.ts.map +1 -1
  37. package/dist/internal/ui/sheet.js +2 -2
  38. package/dist/internal/version-paths.d.ts +49 -0
  39. package/dist/internal/version-paths.d.ts.map +1 -0
  40. package/dist/internal/version-paths.js +57 -0
  41. package/dist/layout.d.ts.map +1 -1
  42. package/dist/layout.js +1 -6
  43. package/dist/mdx.d.ts +1 -0
  44. package/dist/mdx.d.ts.map +1 -1
  45. package/dist/mobile-docs-bar.d.ts.map +1 -1
  46. package/dist/mobile-docs-bar.js +3 -3
  47. package/dist/navbar.js +1 -1
  48. package/dist/pages/docs.d.ts +25 -7
  49. package/dist/pages/docs.d.ts.map +1 -1
  50. package/dist/pages/docs.js +40 -8
  51. package/dist/proxy.d.ts +4 -3
  52. package/dist/proxy.d.ts.map +1 -1
  53. package/dist/proxy.js +124 -46
  54. package/dist/routes/agents.d.ts +1 -1
  55. package/dist/routes/agents.d.ts.map +1 -1
  56. package/dist/routes/agents.js +27 -16
  57. package/dist/routes/chat.d.ts +1 -1
  58. package/dist/routes/chat.d.ts.map +1 -1
  59. package/dist/routes/chat.js +18 -11
  60. package/dist/routes/discovery.d.ts +6 -2
  61. package/dist/routes/discovery.d.ts.map +1 -1
  62. package/dist/routes/discovery.js +6 -12
  63. package/dist/routes/sitemap.d.ts +3 -2
  64. package/dist/routes/sitemap.d.ts.map +1 -1
  65. package/dist/routes/sitemap.js +18 -5
  66. package/dist/source-config.d.ts +1 -0
  67. package/dist/source-config.d.ts.map +1 -1
  68. package/dist/source-config.js +1 -0
  69. package/dist/source.d.ts +40 -2
  70. package/dist/source.d.ts.map +1 -1
  71. package/dist/source.js +132 -15
  72. package/dist/versions.d.ts +22 -2
  73. package/dist/versions.d.ts.map +1 -1
  74. package/dist/versions.js +29 -6
  75. package/docs/agents.md +2 -2
  76. package/docs/llms.txt +313 -31
  77. package/docs/manifest.json +10 -9
  78. package/docs/pages/configuration.md +26 -1
  79. package/docs/pages/getting-started.md +2 -0
  80. package/docs/pages/guides/nested-navigation.md +174 -13
  81. package/docs/pages/md.md +4 -0
  82. package/docs/pages/migration.md +4 -0
  83. package/docs/pages/proxy.md +15 -0
  84. package/docs/pages/rss.md +2 -0
  85. package/docs/pages/syntax.md +2 -1
  86. package/docs/pages/versioned-docs.md +68 -0
  87. package/docs/sitemap.md +1 -1
  88. package/package.json +1 -1
  89. package/source-config.js +1 -0
  90. package/template/AGENTS.md +2 -0
  91. package/template/app/[lang]/rss.xml/route.ts +7 -3
  92. package/template/app/styles/geistdocs.css +8 -6
  93. package/template/content/docs/configuration.mdx +26 -1
  94. package/template/content/docs/getting-started.mdx +2 -0
  95. package/template/content/docs/guides/nested-navigation.mdx +174 -12
  96. package/template/content/docs/md.mdx +4 -0
  97. package/template/content/docs/migration.mdx +4 -0
  98. package/template/content/docs/proxy.mdx +15 -0
  99. package/template/content/docs/rss.mdx +2 -0
  100. package/template/content/docs/syntax.mdx +2 -1
  101. package/template/content/docs/versioned-docs.mdx +68 -0
  102. package/template/package.json +1 -1
  103. package/theme.css +150 -0
package/dist/versions.js CHANGED
@@ -4,6 +4,7 @@ import { ArchiveIcon, BoxIcon, CheckIcon, ChevronDownIcon } from "lucide-react";
4
4
  import { usePathname, useRouter } from "next/navigation";
5
5
  import { cn } from "./internal/cn";
6
6
  import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, } from "./internal/ui/dropdown-menu";
7
+ import { resolveVersionSwitchPath, } from "./internal/version-paths.js";
7
8
  const LEADING_SLASH_PATTERN = /^\//;
8
9
  const PATH_TOKEN_PATTERN = /:path\*|\*path/g;
9
10
  const TRAILING_SLASH_PATTERN = /\/$/;
@@ -17,7 +18,7 @@ const removeRoutePrefix = (pathname, item) => {
17
18
  : pathname;
18
19
  };
19
20
  const getVersionDescription = ({ current, version, }) => version.description ?? (current ? "Current version" : "Previous version");
20
- const SelectIcon = ({ active, children, }) => (_jsx("span", { className: cn("flex size-9 shrink-0 items-center justify-center rounded-lg border", active
21
+ const SelectIcon = ({ active, children, }) => (_jsx("span", { className: cn("flex size-9 shrink-0 items-center justify-center rounded-md border", active
21
22
  ? "border-blue-500 bg-blue-100 text-blue-900"
22
23
  : "border-gray-alpha-400 bg-gray-100 text-gray-800"), children: children }));
23
24
  const VersionIcon = ({ active }) => {
@@ -36,7 +37,14 @@ export const resolveRouteHref = ({ currentItem, item, pathname, }) => {
36
37
  .replace(TRAILING_SLASH_PATTERN, "");
37
38
  }
38
39
  const routePrefix = item.routePrefix?.replace(TRAILING_SLASH_PATTERN, "") ?? "";
39
- const href = `${routePrefix}${pathWithoutCurrentPrefix}`;
40
+ const targetPath = item.paths?.length
41
+ ? (resolveVersionSwitchPath({
42
+ candidate: pathWithoutCurrentPrefix,
43
+ fallbackPath: item.fallbackPath,
44
+ paths: item.paths,
45
+ }) ?? pathWithoutCurrentPrefix)
46
+ : pathWithoutCurrentPrefix;
47
+ const href = `${routePrefix}${targetPath}`;
40
48
  return href || "/";
41
49
  };
42
50
  export const resolveVersionHref = ({ currentVersion, pathname, version, }) => resolveRouteHref({ currentItem: currentVersion, item: version, pathname });
@@ -66,14 +74,29 @@ export const GeistdocsRouteSelect = ({ ariaLabel = "Select route", className, cu
66
74
  const currentDescription = currentItem
67
75
  ? getDescription({ active: true, item: currentItem })
68
76
  : null;
69
- return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs("button", { "aria-label": ariaLabel, className: cn("group flex w-full items-center gap-3 rounded-xl px-2 py-2 text-left outline-none transition-colors hover:bg-gray-100 focus-visible:ring-2 focus-visible:ring-blue-700", className), type: "button", children: [currentItem ? renderIcon({ active: true, item: currentItem }) : null, _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate font-medium text-gray-1000 text-sm leading-5", children: currentItem?.label ?? currentId }), currentDescription ? (_jsx("span", { className: "block truncate text-gray-800 text-sm leading-5", children: currentDescription })) : null] }), _jsx(ChevronDownIcon, { className: "size-4 shrink-0 text-gray-900 transition-transform group-data-[state=open]:rotate-180" })] }) }), _jsx(DropdownMenuContent, { align: "start", className: "w-(--radix-dropdown-menu-trigger-width) min-w-64 rounded-xl bg-background-100 p-1 shadow-(--ds-shadow-menu)", children: items.map((item) => {
77
+ return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs("button", { "aria-label": ariaLabel, className: cn("group flex w-full items-center gap-2 rounded-md px-2 py-2 text-left outline-none transition-colors duration-150 ease-[cubic-bezier(0.175,0.885,0.32,1.1)] hover:bg-gray-alpha-100 focus-visible:shadow-[var(--ds-focus-ring)] active:bg-gray-alpha-300 data-[state=open]:bg-gray-alpha-100 motion-reduce:transition-none", className), type: "button", children: [currentItem ? renderIcon({ active: true, item: currentItem }) : null, _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-button-14 text-gray-1000", children: currentItem?.label ?? currentId }), currentDescription ? (_jsx("span", { className: "block truncate text-gray-900 text-label-13", children: currentDescription })) : null] }), _jsx(ChevronDownIcon, { className: "size-4 shrink-0 text-gray-900 transition-transform duration-150 ease-[cubic-bezier(0.175,0.885,0.32,1.1)] group-data-[state=open]:rotate-180 motion-reduce:transition-none" })] }) }), _jsx(DropdownMenuContent, { align: "start", className: "w-(--radix-dropdown-menu-trigger-width) min-w-64 rounded-xl bg-background-100 p-1 shadow-(--ds-shadow-menu)", children: items.map((item) => {
70
78
  const active = item.id === currentId;
71
79
  const description = getDescription({ active, item });
72
- return (_jsxs(DropdownMenuItem, { className: "flex cursor-pointer items-center gap-3 rounded-lg px-2 py-2", onSelect: () => navigateToItem(item), children: [renderIcon({ active, item }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate font-medium text-gray-1000 text-sm leading-5", children: item.label }), description ? (_jsx("span", { className: "block truncate text-gray-800 text-sm leading-5", children: description })) : null] }), active ? _jsx(CheckIcon, { className: "size-4 text-blue-900" }) : null] }, item.id));
80
+ return (_jsxs(DropdownMenuItem, { "aria-current": active ? "page" : undefined, className: "flex cursor-pointer items-center gap-2 rounded-md px-2 py-2", onSelect: () => navigateToItem(item), children: [renderIcon({ active, item }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-button-14 text-gray-1000", children: item.label }), description ? (_jsx("span", { className: "block truncate text-gray-900 text-label-13", children: description })) : null] }), active ? _jsx(CheckIcon, { className: "size-4 text-blue-900" }) : null] }, item.id));
73
81
  }) })] }));
74
82
  };
75
- export const GeistdocsVersionSelect = ({ className, current, versions, }) => {
76
- const items = Array.isArray(versions) ? versions : versions.items;
83
+ export const GeistdocsVersionSelect = ({ className, current, paths, versions, }) => {
84
+ const baseItems = Array.isArray(versions) ? versions : versions.items;
85
+ const items = paths
86
+ ? baseItems.map((item) => {
87
+ const entry = paths[item.id];
88
+ if (!entry) {
89
+ return item;
90
+ }
91
+ return Array.isArray(entry)
92
+ ? { ...item, paths: entry }
93
+ : {
94
+ ...item,
95
+ fallbackPath: entry.fallbackPath,
96
+ paths: entry.paths,
97
+ };
98
+ })
99
+ : baseItems;
77
100
  const currentId = current ?? (Array.isArray(versions) ? items[0]?.id : versions.current);
78
101
  return (_jsx(GeistdocsRouteSelect, { ariaLabel: "Select documentation version", className: className, current: currentId, getDescription: ({ active, item }) => getVersionDescription({ current: active, version: item }), items: items, renderIcon: ({ active, item }) => item.icon ? (_jsx(SelectIcon, { active: active, children: item.icon })) : (_jsx(VersionIcon, { active: active })) }));
79
102
  };
package/docs/agents.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Docs
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 1.12.0 so agents can understand the installed package without web access.
3
+ These docs are bundled with `@vercel/geistdocs` 1.14.0 so agents can understand the installed package without web access.
4
4
  They are generated from `apps/template/content/docs` during the package build.
5
5
 
6
6
  ## How to use these files
@@ -35,11 +35,11 @@ They are generated from `apps/template/content/docs` during the package build.
35
35
  - [.md Extension](pages/md.md): Access any documentation page as raw Markdown by appending .md or .mdx to the URL for AI tool consumption.
36
36
  - [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.
37
37
  - [Ask AI](pages/ask-ai.md): An AI-powered chat assistant with context-aware search, persistent history, and suggested prompts for your documentation.
38
+ - [Configure sidebar navigation](pages/guides/nested-navigation.md): Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.
38
39
  - [Edit on GitHub](pages/edit-on-github.md): A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
39
40
  - [Feedback](pages/feedback.md): An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
40
41
  - [Internationalization](pages/internationalization.md): Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
41
42
  - [llms.txt](pages/llms-txt.md): A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
42
- - [Nested navigation](pages/guides/nested-navigation.md): How Geistdocs builds breadcrumbs from your page tree.
43
43
  - [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.
44
44
  - [RSS](pages/rss.md): An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
45
45
  - [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.
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.12.0.
3
+ These docs are bundled with `@vercel/geistdocs` 1.14.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
@@ -18,11 +18,11 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
18
18
  - [.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
19
  - [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
20
  - [Ask AI](pages/ask-ai.md): An AI-powered chat assistant with context-aware search, persistent history, and suggested prompts for your documentation.
21
+ - [Configure sidebar navigation](pages/guides/nested-navigation.md): Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.
21
22
  - [Edit on GitHub](pages/edit-on-github.md): A direct link on every documentation page that lets readers propose changes through GitHub pull requests.
22
23
  - [Feedback](pages/feedback.md): An interactive feedback widget that collects user sentiment and creates structured GitHub Issues automatically.
23
24
  - [Internationalization](pages/internationalization.md): Serve documentation in multiple languages with automatic translation via the Geistdocs CLI and Fumadocs routing.
24
25
  - [llms.txt](pages/llms-txt.md): A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
25
- - [Nested navigation](pages/guides/nested-navigation.md): How Geistdocs builds breadcrumbs from your page tree.
26
26
  - [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.
27
27
  - [RSS](pages/rss.md): An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
28
28
  - [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.
@@ -224,6 +224,8 @@ Use `content/docs/meta.json` to control page order and groups:
224
224
  }
225
225
  ```
226
226
 
227
+ Page and folder entries use names without extensions. A value such as `---Guides---` creates a non-clickable separator label. Read [Configure sidebar navigation](/docs/guides/nested-navigation) to add folder landing pages, deeply nested folders, custom links, and `defaultOpen` behavior.
228
+
227
229
  ## Configure the site
228
230
 
229
231
  Use `geistdocs.tsx` to customize the site shell:
@@ -524,6 +526,8 @@ export const geistdocsSource = createSource({
524
526
  });
525
527
  ```
526
528
 
529
+ If the Next.js application also uses `basePath`, pass the same value through `defineConfig` but do not add it to `baseUrl`, `content.route`, `getPageUrl`, or `markdownRoutes`. Those values remain app-local. Geistdocs adds the public prefix to page actions, metadata, generated Markdown, discovery links, chat citations, and proxy destinations.
530
+
527
531
  ## Add route adapters
528
532
 
529
533
  Keep App Router files thin. Route files should call package helpers instead of copying package internals.
@@ -698,6 +702,8 @@ const proxy = createProxy({
698
702
  });
699
703
  ```
700
704
 
705
+ For a base-path application whose root page is documentation, add `"/"` to the static proxy matcher and verify `<basePath>/index.md`. Keep normal application and API paths out of a broad root Markdown mapping with matcher exclusions or a `before` hook.
706
+
701
707
  ## Configure Tailwind CSS
702
708
 
703
709
  Tailwind CSS v4 requires `@source` entries for package components and related dependencies.
@@ -768,6 +774,7 @@ related:
768
774
  - /docs/migration
769
775
  - /docs/provider
770
776
  - /docs/env
777
+ - /docs/guides/nested-navigation
771
778
  - /docs/versioned-docs
772
779
  - /docs/proxy
773
780
  ---
@@ -797,6 +804,8 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
797
804
  | `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
798
805
  | `content/docs/meta.json` | Controls sidebar order and section labels. |
799
806
 
807
+ Read [Configure sidebar navigation](/docs/guides/nested-navigation) for page ordering, titled separators, folder indexes, nested folders, and custom navigation links.
808
+
800
809
  ## `geistdocs.tsx`
801
810
 
802
811
  The root `geistdocs.tsx` file is the primary configuration surface:
@@ -933,6 +942,24 @@ export default defineGeistdocsSourceConfig();
933
942
 
934
943
  To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/"` in `createSource`. Root-mounted docs need explicit `markdownRoutes`; Geistdocs does not infer a broad `/*path` mapping because it can capture homepages and non-docs app routes.
935
944
 
945
+ ## Next.js base paths
946
+
947
+ When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
948
+
949
+ ```ts title="next.config.ts"
950
+ const config: NextConfig = {
951
+ basePath: "/docs",
952
+ };
953
+ ```
954
+
955
+ ```tsx title="geistdocs.tsx"
956
+ export const basePath = "/docs";
957
+ ```
958
+
959
+ Keep `content.route`, source `baseUrl`, navigation links, `getPageUrl`, search results, and proxy `markdownRoutes` app-local. Next.js applies the mount prefix to navigation. Geistdocs applies `basePath` separately to public page actions, Markdown metadata, generated Markdown and sitemap links, Ask AI citations, RSS discovery, and proxy rewrites.
960
+
961
+ For example, a root-mounted source with `baseUrl: "/"` still uses `page.url === "/guide"`. The public page is `/docs/guide`, and its Markdown URL is `/docs/guide.md`. The root page uses `/docs/index.md`.
962
+
936
963
  ## Page actions
937
964
 
938
965
  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`:
@@ -1026,7 +1053,11 @@ const docsPage = createDocsPage({
1026
1053
  });
1027
1054
  ```
1028
1055
 
1029
- Use `getPageUrl` when the public route differs from the source URL, such as `/v5/docs`. Set `openGraph.images` to `true` only when your site includes the Geistdocs OG route. Use `metadata` to set canonical URLs, `robots`, or custom Open Graph fields for a specific route. The `tableOfContent.header` and `tableOfContent.footer` slots render immediately above and below the table of contents.
1056
+ 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`.
1057
+
1058
+ 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.
1059
+
1060
+ Set `openGraph.images` to `true` only when your site includes the Geistdocs OG route. Use `metadata` to set canonical URLs, `robots`, or custom Open Graph fields for a specific route. The `tableOfContent.header` and `tableOfContent.footer` slots render immediately above and below the table of contents.
1030
1061
 
1031
1062
  ## Package-owned runtime
1032
1063
 
@@ -1068,10 +1099,11 @@ Every MDX file should include frontmatter at the top:
1068
1099
  ---
1069
1100
  title: Page Title
1070
1101
  description: A brief description of the page content
1102
+ badge: Beta
1071
1103
  ---
1072
1104
  ```
1073
1105
 
1074
- The `title` property is required and is used for the page heading and navigation. The `description` is used for SEO and page previews.
1106
+ The `title` property is required and is used for the page heading and navigation. The `description` is used for SEO and page previews. The optional `badge` appears beside the page label in desktop and mobile sidebar navigation.
1075
1107
 
1076
1108
  ## Basic Markdown
1077
1109
 
@@ -1786,6 +1818,74 @@ For host-based versions, use `href` instead of `routePrefix`:
1786
1818
  />
1787
1819
  ```
1788
1820
 
1821
+ ## Avoid 404s when switching versions
1822
+
1823
+ By default the selector swaps the route prefix without checking that the page
1824
+ exists in the target version, so pages that exist in only one version 404 on
1825
+ switch. Pass `paths` — computed server-side with `collectVersionSwitchPaths` —
1826
+ and the selector falls back to the nearest existing ancestor (or the version's
1827
+ docs root) instead:
1828
+
1829
+ ```tsx title="app/[lang]/docs/layout.tsx"
1830
+ import { collectVersionSwitchPaths } from "@vercel/geistdocs/source";
1831
+ import { GeistdocsVersionSelect } from "@vercel/geistdocs/versions";
1832
+ import { config } from "@/lib/geistdocs/config";
1833
+ import { versions } from "@/lib/geistdocs/source";
1834
+
1835
+ const DocsLayout = async ({ children, params }) => {
1836
+ const { lang } = await params;
1837
+
1838
+ return (
1839
+ <GeistdocsDocsLayout
1840
+ config={config}
1841
+ sidebarTop={
1842
+ <GeistdocsVersionSelect
1843
+ current={versions.currentVersion}
1844
+ paths={collectVersionSwitchPaths({ lang, versions })}
1845
+ versions={config.versions}
1846
+ />
1847
+ }
1848
+ tree={versions.current.source.pageTree[lang]}
1849
+ >
1850
+ {children}
1851
+ </GeistdocsDocsLayout>
1852
+ );
1853
+ };
1854
+ ```
1855
+
1856
+ `collectVersionSwitchPaths` enumerates every page of every version from the
1857
+ `createVersionedSources` output and returns paths relative to each version's
1858
+ `routePrefix`, plus each version's docs root as the fallback landing page.
1859
+
1860
+ When an app rewrites loader URLs at render time (for example serving a
1861
+ `baseUrl: "/docs"` source under `/v5` with a custom `getPageUrl`), pass the
1862
+ same mapping so the collected paths match the public URLs. For sources that
1863
+ span several loaders per version (for example separate docs and cookbook
1864
+ sources), use the lower-level `collectVersionPaths` per version instead:
1865
+
1866
+ ```tsx
1867
+ import { collectVersionPaths } from "@vercel/geistdocs/source";
1868
+
1869
+ const paths = {
1870
+ v4: {
1871
+ fallbackPath: "/docs",
1872
+ paths: collectVersionPaths({ lang, sources: [v4Docs, v4Cookbook] }),
1873
+ },
1874
+ v5: {
1875
+ fallbackPath: "/docs",
1876
+ paths: collectVersionPaths({
1877
+ lang,
1878
+ routePrefix: "/v5",
1879
+ sources: [v5Docs, v5Cookbook],
1880
+ }),
1881
+ },
1882
+ };
1883
+ ```
1884
+
1885
+ Fallback resolution only applies to `routePrefix` versions. Host-based
1886
+ versions (`href`) always keep the plain path swap, since the target host's
1887
+ pages can't be enumerated locally.
1888
+
1789
1889
  ## Configure markdown routes
1790
1890
 
1791
1891
  Each public route family needs a matching markdown route in `proxy.ts`. Read [Proxy and markdown routes](/docs/proxy) for the proxy configuration.
@@ -1921,6 +2021,8 @@ With these mappings:
1921
2021
 
1922
2022
  Use `[lang]` in the destination when your markdown route is nested under `app/[lang]`. Use `*path` or `:path*` to insert the matched wildcard path.
1923
2023
 
2024
+ `markdownRoutes` are app-local even when `config.basePath` is set. For a Next.js `basePath` of `/docs`, keep a mapping such as `{ from: "/*path", to: "/[lang]/llms.mdx/*path" }`. `createProxy` preserves `/docs` when it rewrites the public request.
2025
+
1924
2026
  ## Root-mounted docs
1925
2027
 
1926
2028
  For docs served from the site root, set the source `baseUrl` and config route to `/`:
@@ -1962,6 +2064,19 @@ const proxy = createProxy({
1962
2064
  });
1963
2065
  ```
1964
2066
 
2067
+ When root-mounted docs are the entire base-path application, include `"/"` explicitly in the static matcher. Next.js does not apply a catch-all matcher to the base-path root:
2068
+
2069
+ ```ts title="proxy.ts"
2070
+ export const config = {
2071
+ matcher: [
2072
+ "/",
2073
+ "/((?!api(?:/|$)|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
2074
+ ],
2075
+ };
2076
+ ```
2077
+
2078
+ The package keeps `llms.txt`, `sitemap.md`, `agents.md`, MCP discovery, and RSS out of root page-Markdown negotiation. Continue to exclude site-specific application and API routes with the matcher or a `before` hook. A root Markdown page is exposed as `/index.md`, or `<basePath>/index.md` publicly.
2079
+
1965
2080
  ## Hook context
1966
2081
 
1967
2082
  Both `before` and `after` receive the same context:
@@ -2021,6 +2136,10 @@ The `.mdx` version returns:
2021
2136
  - The full processed Markdown content
2022
2137
  - No HTML, styling, or navigation
2023
2138
 
2139
+ 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`.
2140
+
2141
+ Copy Page, View as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
2142
+
2024
2143
  ## Use cases
2025
2144
 
2026
2145
  This feature is particularly useful for:
@@ -2378,6 +2497,194 @@ In default AI Gateway mode, Geistdocs uses `openai/gpt-4.1-mini` via the Vercel
2378
2497
  You can customize the initial suggested prompts shown to users. These are configured in the Geistdocs configuration file, which you can read more about in the [Configuration](/docs/configuration) section.
2379
2498
 
2380
2499
 
2500
+ ---
2501
+
2502
+ ---
2503
+ title: Configure sidebar navigation
2504
+ description: Organize Geistdocs pages with ordered groups, separators, folder indexes, and nested navigation
2505
+ type: guide
2506
+ summary: Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.
2507
+ url: /docs/guides/nested-navigation
2508
+ source: apps/template/content/docs/guides/nested-navigation.mdx
2509
+ prerequisites:
2510
+ - /docs/getting-started
2511
+ related:
2512
+ - /docs/configuration
2513
+ - /docs/syntax
2514
+ ---
2515
+
2516
+ # Configure sidebar navigation
2517
+
2518
+ Use `meta.json` files to organize the Geistdocs sidebar without changing layout components. Each `meta.json` controls the pages and folders in its own directory, so the same pattern works at every nesting level.
2519
+
2520
+ ## Start with the content tree
2521
+
2522
+ Directories become sidebar folders, and `.mdx` files become pages. The examples on this page use the following content tree:
2523
+
2524
+ ```text
2525
+ content/docs/
2526
+ ├── index.mdx
2527
+ ├── getting-started.mdx
2528
+ ├── architecture.mdx
2529
+ ├── api-reference.mdx
2530
+ ├── changelog.mdx
2531
+ ├── meta.json
2532
+ └── guides/
2533
+ ├── index.mdx
2534
+ ├── quickstarts.mdx
2535
+ ├── meta.json
2536
+ └── integrations/
2537
+ ├── nextjs.mdx
2538
+ ├── sveltekit.mdx
2539
+ ├── meta.json
2540
+ └── advanced/
2541
+ ├── index.mdx
2542
+ ├── caching.mdx
2543
+ ├── security.mdx
2544
+ └── meta.json
2545
+ ```
2546
+
2547
+ Every page needs a frontmatter `title`. Add a `description` to summarize the page. For a regular page, the frontmatter title becomes its sidebar label. Folder landing pages use the folder behavior described below.
2548
+
2549
+ ## Order top-level pages and add separators
2550
+
2551
+ Add page and folder names to the root `pages` array without file extensions:
2552
+
2553
+ ```json title="content/docs/meta.json"
2554
+ {
2555
+ "title": "My Product Documentation",
2556
+ "root": true,
2557
+ "pages": [
2558
+ "index",
2559
+ "getting-started",
2560
+ "---Guides---",
2561
+ "guides",
2562
+ "---Internals---",
2563
+ "architecture",
2564
+ "api-reference",
2565
+ "---Resources---",
2566
+ "..."
2567
+ ]
2568
+ }
2569
+ ```
2570
+
2571
+ This configuration produces three labeled groups after the two introductory pages:
2572
+
2573
+ - `---Guides---` adds a non-clickable **Guides** separator before the `guides` folder.
2574
+ - `---Internals---` adds an **Internals** separator before the architecture and API reference pages.
2575
+ - `---Resources---` adds a **Resources** separator before pages inserted by `...`.
2576
+
2577
+ The `...` entry inserts every page or folder that is not named elsewhere in the array. Place it where the remaining items should appear. Without `...`, unnamed items do not appear in that folder's sidebar navigation.
2578
+
2579
+ On desktop, top-level folders open as dedicated sidebar sections. On mobile, Geistdocs renders the same page tree as expandable nested navigation. Both layouts use the same `meta.json` files.
2580
+
2581
+ ## Add a folder landing page
2582
+
2583
+ Create `index.mdx` inside a nested directory when the folder needs its own landing page:
2584
+
2585
+ ```mdx title="content/docs/guides/index.mdx"
2586
+ ---
2587
+ title: Guides
2588
+ description: Follow task-focused guides for My Product.
2589
+ ---
2590
+
2591
+ Choose a guide based on the workflow you want to complete.
2592
+ ```
2593
+
2594
+ Then order the folder's child pages in its `meta.json`:
2595
+
2596
+ ```json title="content/docs/guides/meta.json"
2597
+ {
2598
+ "title": "Guides",
2599
+ "pages": ["quickstarts", "integrations"]
2600
+ }
2601
+ ```
2602
+
2603
+ Leave `index` out of a nested folder's `pages` array to use `index.mdx` as the folder landing page. In the desktop section view, Geistdocs exposes a top-level folder index as **Overview**. For a nested folder, the folder label links to its index while the disclosure control expands its children.
2604
+
2605
+ If you include `index` explicitly in `pages`, Geistdocs treats it as a regular child page instead of the folder landing page.
2606
+
2607
+ ## Configure deeply nested folders
2608
+
2609
+ Add another `meta.json` inside each nested directory. For the `integrations` folder from the example tree, group framework pages separately from advanced topics:
2610
+
2611
+ ```json title="content/docs/guides/integrations/meta.json"
2612
+ {
2613
+ "title": "Integrations",
2614
+ "defaultOpen": true,
2615
+ "pages": [
2616
+ "---Frameworks---",
2617
+ "nextjs",
2618
+ "sveltekit",
2619
+ "---Advanced---",
2620
+ "advanced"
2621
+ ]
2622
+ }
2623
+ ```
2624
+
2625
+ The `advanced` directory can define another level:
2626
+
2627
+ ```json title="content/docs/guides/integrations/advanced/meta.json"
2628
+ {
2629
+ "title": "Advanced Integrations",
2630
+ "pages": ["caching", "security"]
2631
+ }
2632
+ ```
2633
+
2634
+ Because `advanced/index.mdx` exists and is not listed in `pages`, **Advanced Integrations** links to `/docs/guides/integrations/advanced`. Its child pages resolve to:
2635
+
2636
+ - `/docs/guides/integrations/advanced/caching`
2637
+ - `/docs/guides/integrations/advanced/security`
2638
+
2639
+ Set `defaultOpen` to `true` when a folder should start expanded. Geistdocs also opens the folders that contain the active page, unless a folder explicitly sets `defaultOpen` to `false`.
2640
+
2641
+ ## Add a badge to a page
2642
+
2643
+ Add a short `badge` value to page frontmatter to show status or availability beside its sidebar label:
2644
+
2645
+ ```yaml title="content/docs/guides/new-api.mdx"
2646
+ ---
2647
+ title: New API
2648
+ description: Use the new API in your application.
2649
+ badge: Beta
2650
+ ---
2651
+ ```
2652
+
2653
+ Geistdocs renders the badge in desktop and mobile navigation. Badges also appear on folder landing pages because their sidebar items use the folder's `index.mdx` frontmatter. Keep badge text short so the page label has enough room to remain readable.
2654
+
2655
+ ## Add links to the navigation
2656
+
2657
+ The `pages` array can include internal and external links alongside content files:
2658
+
2659
+ ```json title="content/docs/meta.json"
2660
+ {
2661
+ "pages": [
2662
+ "index",
2663
+ "[Status](/status)",
2664
+ "external:[GitHub](https://github.com/my-org/my-repo)"
2665
+ ]
2666
+ }
2667
+ ```
2668
+
2669
+ Use `[Label](/path)` for an internal link. Prefix an external link with `external:` so Geistdocs opens it in a new tab and shows the external-link indicator.
2670
+
2671
+ ## Check breadcrumbs for nested pages
2672
+
2673
+ Geistdocs builds breadcrumbs from the same page tree. A page at `content/docs/guides/integrations/advanced/caching.mdx` receives the folder path **Guides**, **Integrations**, and **Advanced Integrations** before its page title.
2674
+
2675
+ Breadcrumbs render on the server from the page URL and sidebar tree, so they are present in the initial HTML. Top-level pages have no folder ancestors and do not render a breadcrumb.
2676
+
2677
+ ## Troubleshoot missing navigation items
2678
+
2679
+ Check these rules when a page or folder does not appear where expected:
2680
+
2681
+ - Match each `pages` entry to a file or directory name without its extension.
2682
+ - Add a `meta.json` to every folder that needs custom ordering, separators, `defaultOpen` behavior, or a title override.
2683
+ - Add `...` when unlisted files and folders should remain visible.
2684
+ - Leave `index` out of a nested folder's `pages` array when it should act as the folder landing page.
2685
+ - Keep separator labels between three hyphens on each side, such as `---Internals---`.
2686
+
2687
+
2381
2688
  ---
2382
2689
 
2383
2690
  ---
@@ -2750,33 +3057,6 @@ The llms.txt standard is a simple convention that makes documentation more acces
2750
3057
  Learn more at [llmstxt.org](https://llmstxt.org/)
2751
3058
 
2752
3059
 
2753
- ---
2754
-
2755
- ---
2756
- title: Nested navigation
2757
- description: How Geistdocs builds breadcrumbs from your page tree.
2758
- type: guide
2759
- url: /docs/guides/nested-navigation
2760
- source: apps/template/content/docs/guides/nested-navigation.mdx
2761
- ---
2762
-
2763
- # Nested navigation
2764
-
2765
- Any page nested inside a folder shows a breadcrumb above its title, built
2766
- automatically from the page tree. This page lives under the **Guides** folder,
2767
- so the breadcrumb above reads _Guides_.
2768
-
2769
- ## How it works
2770
-
2771
- The breadcrumb lists the folder ancestors of the current page, in order. It is
2772
- rendered on the server from the page's URL and the sidebar tree, so it is
2773
- present in the initial HTML — the page title never shifts once the page
2774
- hydrates.
2775
-
2776
- Top-level pages (those not inside a folder) have no ancestors, so no breadcrumb
2777
- is shown.
2778
-
2779
-
2780
3060
  ---
2781
3061
 
2782
3062
  ---
@@ -2914,6 +3194,8 @@ Users can subscribe to this URL using:
2914
3194
 
2915
3195
  An RSS button appears in the navigation bar so readers can discover and subscribe to your feed. Clicking the button opens the RSS XML in a new tab.
2916
3196
 
3197
+ The package Footer applies `config.basePath` to this link. Custom RSS generators must also apply the base path to channel and item URLs; source `page.url` values intentionally remain app-local for Next.js navigation.
3198
+
2917
3199
  ## Feed Format
2918
3200
 
2919
3201
  The RSS feed follows the RSS 2.0 specification and includes:
@@ -125,6 +125,15 @@
125
125
  "type": "conceptual",
126
126
  "url": "/docs/ask-ai"
127
127
  },
128
+ {
129
+ "description": "Organize Geistdocs pages with ordered groups, separators, folder indexes, and nested navigation",
130
+ "path": "pages/guides/nested-navigation.md",
131
+ "source": "apps/template/content/docs/guides/nested-navigation.mdx",
132
+ "summary": "Configure sidebar order, section labels, folder landing pages, and deeply nested page trees with meta.json files.",
133
+ "title": "Configure sidebar navigation",
134
+ "type": "guide",
135
+ "url": "/docs/guides/nested-navigation"
136
+ },
128
137
  {
129
138
  "description": "Allow readers to contribute directly by editing documentation pages on GitHub",
130
139
  "path": "pages/edit-on-github.md",
@@ -161,14 +170,6 @@
161
170
  "type": "conceptual",
162
171
  "url": "/docs/llms-txt"
163
172
  },
164
- {
165
- "description": "How Geistdocs builds breadcrumbs from your page tree.",
166
- "path": "pages/guides/nested-navigation.md",
167
- "source": "apps/template/content/docs/guides/nested-navigation.mdx",
168
- "title": "Nested navigation",
169
- "type": "guide",
170
- "url": "/docs/guides/nested-navigation"
171
- },
172
173
  {
173
174
  "description": "Allow users to continue conversations in their preferred AI chat platform with a single click",
174
175
  "path": "pages/open-in-chat.md",
@@ -198,5 +199,5 @@
198
199
  }
199
200
  ],
200
201
  "source": "apps/template/content/docs",
201
- "version": "1.12.0"
202
+ "version": "1.14.0"
202
203
  }
@@ -11,6 +11,7 @@ related:
11
11
  - /docs/migration
12
12
  - /docs/provider
13
13
  - /docs/env
14
+ - /docs/guides/nested-navigation
14
15
  - /docs/versioned-docs
15
16
  - /docs/proxy
16
17
  ---
@@ -40,6 +41,8 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
40
41
  | `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
41
42
  | `content/docs/meta.json` | Controls sidebar order and section labels. |
42
43
 
44
+ Read [Configure sidebar navigation](/docs/guides/nested-navigation) for page ordering, titled separators, folder indexes, nested folders, and custom navigation links.
45
+
43
46
  ## `geistdocs.tsx`
44
47
 
45
48
  The root `geistdocs.tsx` file is the primary configuration surface:
@@ -176,6 +179,24 @@ export default defineGeistdocsSourceConfig();
176
179
 
177
180
  To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/"` in `createSource`. Root-mounted docs need explicit `markdownRoutes`; Geistdocs does not infer a broad `/*path` mapping because it can capture homepages and non-docs app routes.
178
181
 
182
+ ## Next.js base paths
183
+
184
+ When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
185
+
186
+ ```ts title="next.config.ts"
187
+ const config: NextConfig = {
188
+ basePath: "/docs",
189
+ };
190
+ ```
191
+
192
+ ```tsx title="geistdocs.tsx"
193
+ export const basePath = "/docs";
194
+ ```
195
+
196
+ Keep `content.route`, source `baseUrl`, navigation links, `getPageUrl`, search results, and proxy `markdownRoutes` app-local. Next.js applies the mount prefix to navigation. Geistdocs applies `basePath` separately to public page actions, Markdown metadata, generated Markdown and sitemap links, Ask AI citations, RSS discovery, and proxy rewrites.
197
+
198
+ For example, a root-mounted source with `baseUrl: "/"` still uses `page.url === "/guide"`. The public page is `/docs/guide`, and its Markdown URL is `/docs/guide.md`. The root page uses `/docs/index.md`.
199
+
179
200
  ## Page actions
180
201
 
181
202
  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`:
@@ -269,7 +290,11 @@ const docsPage = createDocsPage({
269
290
  });
270
291
  ```
271
292
 
272
- Use `getPageUrl` when the public route differs from the source URL, such as `/v5/docs`. Set `openGraph.images` to `true` only when your site includes the Geistdocs OG route. Use `metadata` to set canonical URLs, `robots`, or custom Open Graph fields for a specific route. The `tableOfContent.header` and `tableOfContent.footer` slots render immediately above and below the table of contents.
293
+ 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`.
294
+
295
+ 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.
296
+
297
+ Set `openGraph.images` to `true` only when your site includes the Geistdocs OG route. Use `metadata` to set canonical URLs, `robots`, or custom Open Graph fields for a specific route. The `tableOfContent.header` and `tableOfContent.footer` slots render immediately above and below the table of contents.
273
298
 
274
299
  ## Package-owned runtime
275
300
 
@@ -90,6 +90,8 @@ Use `content/docs/meta.json` to control page order and groups:
90
90
  }
91
91
  ```
92
92
 
93
+ Page and folder entries use names without extensions. A value such as `---Guides---` creates a non-clickable separator label. Read [Configure sidebar navigation](/docs/guides/nested-navigation) to add folder landing pages, deeply nested folders, custom links, and `defaultOpen` behavior.
94
+
93
95
  ## Configure the site
94
96
 
95
97
  Use `geistdocs.tsx` to customize the site shell: