@vercel/geistdocs 1.24.1 → 1.25.1

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 (46) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/components/code-block.d.ts.map +1 -1
  3. package/dist/components/code-block.js +2 -2
  4. package/dist/components/copy-prompt.js +1 -1
  5. package/dist/home-layout.js +1 -1
  6. package/dist/internal/app-route-manifest.d.ts +19 -0
  7. package/dist/internal/app-route-manifest.d.ts.map +1 -0
  8. package/dist/internal/app-route-manifest.js +121 -0
  9. package/dist/internal/app-route-scanner.d.ts +9 -0
  10. package/dist/internal/app-route-scanner.d.ts.map +1 -0
  11. package/dist/internal/app-route-scanner.js +149 -0
  12. package/dist/internal/chat/shell.d.ts.map +1 -1
  13. package/dist/internal/chat/shell.js +1 -1
  14. package/dist/internal/navbar/desktop-menu.d.ts.map +1 -1
  15. package/dist/internal/navbar/desktop-menu.js +1 -1
  16. package/dist/internal/navbar/navbar-logo.d.ts.map +1 -1
  17. package/dist/internal/navbar/navbar-logo.js +2 -2
  18. package/dist/internal/ui/button.d.ts +1 -1
  19. package/dist/internal/ui/kbd.js +1 -1
  20. package/dist/layout.js +1 -1
  21. package/dist/next.d.ts +6 -0
  22. package/dist/next.d.ts.map +1 -0
  23. package/dist/next.js +52 -0
  24. package/dist/proxy.d.ts +2 -1
  25. package/dist/proxy.d.ts.map +1 -1
  26. package/dist/proxy.js +28 -5
  27. package/dist/routes/llms.d.ts +1 -1
  28. package/dist/routes/llms.d.ts.map +1 -1
  29. package/dist/routes/llms.js +1 -1
  30. package/docs/agents.md +2 -2
  31. package/docs/llms.txt +45 -13
  32. package/docs/manifest.json +2 -2
  33. package/docs/pages/configuration.md +8 -0
  34. package/docs/pages/md.md +8 -5
  35. package/docs/pages/migration.md +7 -5
  36. package/docs/pages/proxy.md +20 -1
  37. package/docs/sitemap.md +1 -1
  38. package/package.json +5 -1
  39. package/template/AGENTS.md +2 -0
  40. package/template/app/[lang]/llms.mdx/[[...slug]]/route.ts +0 -1
  41. package/template/content/docs/configuration.mdx +8 -0
  42. package/template/content/docs/md.mdx +8 -5
  43. package/template/content/docs/migration.mdx +7 -5
  44. package/template/content/docs/proxy.mdx +20 -1
  45. package/template/next.config.ts +3 -3
  46. package/template/package.json +1 -1
@@ -1 +1 @@
1
- {"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,UAAU,CAAC;AAIlB,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,iBAAiB,GACjB,WAAW,GACX,IAAI,CAAC;AAET,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,GAAG,mBAAmB,GAAG,eAAe,CAAC;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,KAAK,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC;AAEnD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;IACnB,EAAE,EACE,IAAI,MAAM,EAAE,GACZ,CAAC,CAAC,OAAO,EAAE;QACT,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,KAAK,IAAI,MAAM,EAAE,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IAClD,MAAM,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IACnD,MAAM,EAAE,IAAI,CACV,eAAe,EACf,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,iBAAiB,GAAG,cAAc,CACtE,CAAC;IACF,gBAAgB,CAAC,EACb,IAAI,GACJ,CAAC,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC;IACnE,cAAc,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC1C,oBAAoB,CAAC,EAAE,CACrB,KAAK,EAAE,yBAAyB,KAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B;AAmKD,eAAO,MAAM,WAAW,GAAI,oFAOzB,kBAAkB,MA0QL,SAAS,WAAW,EAAE,SAAS,cAAc,sBAiD5D,CAAC"}
1
+ {"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,UAAU,CAAC;AAQlB,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,iBAAiB,GACjB,WAAW,GACX,IAAI,CAAC;AAET,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,GAAG,mBAAmB,GAAG,eAAe,CAAC;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,KAAK,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC;AAEnD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;IACnB,EAAE,EACE,IAAI,MAAM,EAAE,GACZ,CAAC,CAAC,OAAO,EAAE;QACT,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,KAAK,IAAI,MAAM,EAAE,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IAClD,MAAM,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IACnD,MAAM,EAAE,IAAI,CACV,eAAe,EACf,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,iBAAiB,GAAG,cAAc,CACtE,CAAC;IACF,sFAAsF;IACtF,gBAAgB,CAAC,EACb,OAAO,GACP,CAAC,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC;IACnE,cAAc,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC1C,oBAAoB,CAAC,EAAE,CACrB,KAAK,EAAE,yBAAyB,KAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B;AAoKD,eAAO,MAAM,WAAW,GAAI,oFAOzB,kBAAkB,MA6SL,SAAS,WAAW,EAAE,SAAS,cAAc,sBAoD5D,CAAC"}
package/dist/proxy.js CHANGED
@@ -4,6 +4,7 @@ import { createI18nMiddleware } from "fumadocs-core/i18n/middleware";
4
4
  import { isMarkdownPreferred } from "fumadocs-core/negotiation";
5
5
  import { NextResponse, } from "next/server";
6
6
  import { getPublicPath, normalizeBasePath, } from "./config";
7
+ import { matchesAppRoute, parseAppRouteManifest, } from "./internal/app-route-manifest";
7
8
  import { renderNotFoundMarkdown } from "./internal/not-found";
8
9
  import { localizeHref } from "./localize-href";
9
10
  const MDX_EXTENSION_PATTERN = /\.mdx?$/;
@@ -25,6 +26,7 @@ const PACKAGE_ROUTE_PATHS = new Set([
25
26
  "/rss.xml",
26
27
  "/sitemap.md",
27
28
  ]);
29
+ const MARKDOWN_REQUEST_METHODS = new Set(["GET", "HEAD"]);
28
30
  const TRAILING_SLASH_PATTERN = /\/$/;
29
31
  const getLanguages = (config) => {
30
32
  const defaultLanguage = config.defaultLanguage ?? "en";
@@ -120,11 +122,13 @@ const getLocalizedPathname = (pathname, languages, defaultLanguage) => {
120
122
  };
121
123
  };
122
124
  export const createProxy = ({ after, before, config, markdownNotFound, markdownRoutes, trackMarkdownRequest, }) => {
125
+ const agentEnabled = config.agent !== undefined && config.agent.enabled !== false;
123
126
  const contentRouteMappings = markdownRoutes ??
124
127
  inferMarkdownRoutes(config) ?? [DEFAULT_MARKDOWN_ROUTE];
125
- const routeMappings = config.agent && config.agent.enabled !== false
128
+ const routeMappings = agentEnabled
126
129
  ? [...contentRouteMappings, HOME_MARKDOWN_ROUTE]
127
130
  : contentRouteMappings;
131
+ const appRouteManifest = parseAppRouteManifest(process.env.GEISTDOCS_APP_ROUTE_MANIFEST);
128
132
  const { defaultLanguage, languages } = getLanguages(config);
129
133
  const i18n = defineI18n({
130
134
  defaultLanguage,
@@ -155,8 +159,23 @@ export const createProxy = ({ after, before, config, markdownNotFound, markdownR
155
159
  }),
156
160
  });
157
161
  };
158
- const shouldCreateMarkdownNotFound = (pathname, language) => markdownNotFound === true ||
159
- markdownNotFound?.({ language, pathname }) === true;
162
+ const shouldCreateMarkdownNotFound = (pathname, language, requestPathname) => {
163
+ if (markdownNotFound === true) {
164
+ return true;
165
+ }
166
+ if (markdownNotFound === false) {
167
+ return false;
168
+ }
169
+ if (typeof markdownNotFound === "function") {
170
+ return markdownNotFound({ language, pathname });
171
+ }
172
+ return Boolean(agentEnabled &&
173
+ appRouteManifest &&
174
+ !matchesAppRoute(appRouteManifest, {
175
+ localizedPathname: pathname,
176
+ pathname: requestPathname,
177
+ }));
178
+ };
160
179
  const resolveMarkdownRewrite = (pathname, language) => {
161
180
  for (const route of routeMappings) {
162
181
  const path = getRoutePath(route, pathname);
@@ -230,6 +249,9 @@ export const createProxy = ({ after, before, config, markdownNotFound, markdownR
230
249
  })
231
250
  : null;
232
251
  const handleMarkdownNegotiation = (request, context, pathname) => {
252
+ if (!MARKDOWN_REQUEST_METHODS.has(request.method)) {
253
+ return null;
254
+ }
233
255
  const localized = getLocalizedPathname(pathname, languages, defaultLanguage);
234
256
  if ((localized.hasLanguagePrefix && localized.language === defaultLanguage) ||
235
257
  PACKAGE_ROUTE_PATHS.has(localized.pathname)) {
@@ -252,7 +274,7 @@ export const createProxy = ({ after, before, config, markdownNotFound, markdownR
252
274
  }
253
275
  return !RESOURCE_EXTENSION_PATTERN.test(localized.pathname) &&
254
276
  (isMarkdownPreferred(request) || isAIAgent(request).detected) &&
255
- shouldCreateMarkdownNotFound(localized.pathname, localized.language)
277
+ shouldCreateMarkdownNotFound(localized.pathname, localized.language, pathname)
256
278
  ? createMarkdownNotFound(pathname, localized.language)
257
279
  : null;
258
280
  };
@@ -296,7 +318,8 @@ export const createProxy = ({ after, before, config, markdownNotFound, markdownR
296
318
  return afterResponse;
297
319
  }
298
320
  const response = await handleI18nRequest(request, context);
299
- if (resolveMarkdownRewrite(localized.pathname, localized.language)) {
321
+ if (MARKDOWN_REQUEST_METHODS.has(request.method) &&
322
+ resolveMarkdownRewrite(localized.pathname, localized.language)) {
300
323
  applyMarkdownHeaders(response.headers);
301
324
  }
302
325
  return response;
@@ -32,7 +32,7 @@ export declare const createLlmsRoute: ({ filterPage, source, sources, transform,
32
32
  export interface CreateDocsMarkdownRouteOptions {
33
33
  config?: Pick<GeistdocsConfig, "basePath" | "defaultLanguage" | "translations">;
34
34
  filterStaticParams?: (params: DocsMarkdownParams) => boolean;
35
- /** Enable an agent-readable Markdown response for missing pages. */
35
+ /** Customize the agent-readable Markdown response for missing pages, or disable it. */
36
36
  notFound?: false | MarkdownNotFoundOptions;
37
37
  source?: SourceBundle;
38
38
  sources?: SourceBundle[];
@@ -1 +1 @@
1
- {"version":3,"file":"llms.d.ts","sourceRoot":"","sources":["../../src/routes/llms.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,cAAc,CAAC;AAStB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,KAAK,YAAY,GAAG,qBAAqB,CAAC;AAC1C,KAAK,aAAa,GAAG,WAAW,CAAC,UAAU,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAahF,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,UAAU,wBAAwB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,KAAK,iBAAiB,GAAG,CACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,wBAAwB,KAC9B,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;AAE9B,UAAU,sBAAsB;IAC9B,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;IACzE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAqOD,eAAO,MAAM,eAAe,GAAI,6CAK7B,sBAAsB;gBAIf,WAAW,cACL;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;;CAoCpD,CAAC;AAEF,MAAM,WAAW,8BAA8B;IAC7C,MAAM,CAAC,EAAE,IAAI,CACX,eAAe,EACf,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAChD,CAAC;IACF,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAC;IAC7D,oEAAoE;IACpE,QAAQ,CAAC,EAAE,KAAK,GAAG,uBAAuB,CAAC;IAC3C,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC7B,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,aAAa,CAAC;QACpB,MAAM,EAAE,YAAY,CAAC;KACtB,KAAK,MAAM,CAAC;IACb;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,MAAM,CAAC;IACzE,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;CAC1B;AAED,eAAO,MAAM,uBAAuB,GAAI,wFAOrC,8BAA8B;mBAkLpB,OAAO,cACJ;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAA;KAAE;yCA6CjE;QACD,MAAM,CAAC,EAAE,OAAO,CAAC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACrC;;CAgBF,CAAC"}
1
+ {"version":3,"file":"llms.d.ts","sourceRoot":"","sources":["../../src/routes/llms.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,cAAc,CAAC;AAStB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,KAAK,YAAY,GAAG,qBAAqB,CAAC;AAC1C,KAAK,aAAa,GAAG,WAAW,CAAC,UAAU,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAahF,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,UAAU,wBAAwB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,KAAK,iBAAiB,GAAG,CACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,wBAAwB,KAC9B,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;AAE9B,UAAU,sBAAsB;IAC9B,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;IACzE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAqOD,eAAO,MAAM,eAAe,GAAI,6CAK7B,sBAAsB;gBAIf,WAAW,cACL;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;;CAoCpD,CAAC;AAEF,MAAM,WAAW,8BAA8B;IAC7C,MAAM,CAAC,EAAE,IAAI,CACX,eAAe,EACf,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAChD,CAAC;IACF,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAC;IAC7D,uFAAuF;IACvF,QAAQ,CAAC,EAAE,KAAK,GAAG,uBAAuB,CAAC;IAC3C,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC7B,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,aAAa,CAAC;QACpB,MAAM,EAAE,YAAY,CAAC;KACtB,KAAK,MAAM,CAAC;IACb;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,MAAM,CAAC;IACzE,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;CAC1B;AAED,eAAO,MAAM,uBAAuB,GAAI,wFAOrC,8BAA8B;mBAkLpB,OAAO,cACJ;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAA;KAAE;yCA6CjE;QACD,MAAM,CAAC,EAAE,OAAO,CAAC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACrC;;CAgBF,CAAC"}
@@ -156,7 +156,7 @@ export const createLlmsRoute = ({ filterPage, source, sources, transform, }) =>
156
156
  revalidate: false,
157
157
  };
158
158
  };
159
- export const createDocsMarkdownRoute = ({ config, filterStaticParams, notFound: notFoundOptions = false, source, sources, transform, }) => {
159
+ export const createDocsMarkdownRoute = ({ config, filterStaticParams, notFound: notFoundOptions = {}, source, sources, transform, }) => {
160
160
  const routeSources = resolveSources(source, sources, "createDocsMarkdownRoute");
161
161
  const routingConfig = config ?? routeSources[0].routingConfig ?? {};
162
162
  const smartNotFoundOptions = notFoundOptions === false ? {} : notFoundOptions;
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.24.1 so agents can understand the installed package without web access.
3
+ These docs are bundled with `@vercel/geistdocs` 1.25.1 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
@@ -31,7 +31,7 @@ They are generated from `apps/template/content/docs` during the package build.
31
31
  - [Syntax](pages/syntax.md): Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
32
32
  - [Geistdocs Provider](pages/provider.md): The root provider component that wraps your application to handle toast notifications, search, and analytics.
33
33
  - [Versioned docs](pages/versioned-docs.md): Use createVersionedSources to configure stable, pre-release, or host-based documentation versions.
34
- - [Proxy and markdown routes](pages/proxy.md): Configure createProxy with before and after hooks, markdown route mappings, and a static Next.js matcher.
34
+ - [Proxy and markdown routes](pages/proxy.md): Configure createProxy with generated route discovery, request hooks, markdown mappings, and a static Next.js matcher.
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.
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.24.1.
3
+ These docs are bundled with `@vercel/geistdocs` 1.25.1.
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
@@ -14,7 +14,7 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
14
14
  - [Syntax](pages/syntax.md): Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
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
- - [Proxy and markdown routes](pages/proxy.md): Configure createProxy with before and after hooks, markdown route mappings, and a static Next.js matcher.
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
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.
@@ -438,24 +438,26 @@ If you are starting from a generated Geistdocs project and moving content into i
438
438
  pnpm dlx @vercel/geistdocs init --name my-docs
439
439
  ```
440
440
 
441
- ## Enable Cache Components
441
+ ## Configure Next.js
442
442
 
443
- Geistdocs uses Next.js Cache Components to prerender static application shells while dynamic content streams from the server. Enable Cache Components in `next.config.ts`:
443
+ The Geistdocs Next.js integration composes Fumadocs MDX, enables automatic app-route discovery for agent-readable 404s, and preserves your Next.js configuration. Enable Cache Components in the same file:
444
444
 
445
445
  ```ts title="next.config.ts"
446
- import { createMDX } from "fumadocs-mdx/next";
446
+ import { createGeistdocs } from "@vercel/geistdocs/next";
447
447
  import type { NextConfig } from "next";
448
448
 
449
- const withMDX = createMDX();
449
+ const withGeistdocs = createGeistdocs();
450
450
 
451
451
  const config: NextConfig = {
452
452
  cacheComponents: true,
453
453
  partialPrefetching: true,
454
454
  };
455
455
 
456
- export default withMDX(config);
456
+ export default withGeistdocs(config);
457
457
  ```
458
458
 
459
+ Restart `next dev` after adding, deleting, or renaming an App Router page or route. Production builds always regenerate the route manifest.
460
+
459
461
  Every root dynamic parameter needs at least one value from `generateStaticParams`. For a site with a `[lang]` root segment, return every configured language from the root layout:
460
462
 
461
463
  ```tsx title="app/[lang]/layout.tsx"
@@ -836,6 +838,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
836
838
  | File | Purpose |
837
839
  | --- | --- |
838
840
  | `geistdocs.tsx` | Site-level settings, including logo, nav, GitHub repo, AI prompt, agent-readiness metadata, translations, and feature flags. |
841
+ | `next.config.ts` | Composes Fumadocs MDX, discovers App Router routes, and configures Next.js. |
839
842
  | `source.config.ts` | Configures Fumadocs collections with the package-provided schema, Markdown plugins, and syntax theme. |
840
843
  | `lib/geistdocs/config.tsx` | Converts `geistdocs.tsx` exports into the package config using `defineConfig`. |
841
844
  | `source.config.ts` | Configures Fumadocs collections with package-safe schemas and Markdown processing. |
@@ -1025,11 +1028,18 @@ To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/
1025
1028
  When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
1026
1029
 
1027
1030
  ```ts title="next.config.ts"
1031
+ import { createGeistdocs } from "@vercel/geistdocs/next";
1032
+ import type { NextConfig } from "next";
1033
+
1034
+ const withGeistdocs = createGeistdocs();
1035
+
1028
1036
  const config: NextConfig = {
1029
1037
  basePath: "/docs",
1030
1038
  cacheComponents: true,
1031
1039
  partialPrefetching: true,
1032
1040
  };
1041
+
1042
+ export default withGeistdocs(config);
1033
1043
  ```
1034
1044
 
1035
1045
  ```tsx title="geistdocs.tsx"
@@ -2012,7 +2022,7 @@ Each public route family needs a matching markdown route in `proxy.ts`. Read [Pr
2012
2022
  title: Proxy and markdown routes
2013
2023
  description: Add custom request logic while keeping Geistdocs markdown negotiation in the package
2014
2024
  type: reference
2015
- summary: Configure createProxy with before and after hooks, markdown route mappings, and a static Next.js matcher.
2025
+ summary: Configure createProxy with generated route discovery, request hooks, markdown mappings, and a static Next.js matcher.
2016
2026
  url: /docs/proxy
2017
2027
  source: apps/template/content/docs/proxy.mdx
2018
2028
  prerequisites:
@@ -2189,6 +2199,25 @@ export const config = {
2189
2199
 
2190
2200
  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.
2191
2201
 
2202
+ ## Recover unmatched Markdown requests
2203
+
2204
+ `createGeistdocs` in `next.config.ts` generates a lightweight manifest from App Router pages and route handlers. When `agent` is enabled, `createProxy` uses this manifest to return a Markdown 404 only when a `GET` or `HEAD` request matches neither a Markdown mapping nor an application route.
2205
+
2206
+ The manifest contains route patterns, not page modules or content. Static, dynamic, catch-all, optional catch-all, grouped, and localized routes continue to Next.js. Root catch-all pages are treated as potentially valid, so the app remains responsible for their 404 behavior. The package's own `[...not-found]` route handler is excluded so it does not claim every path.
2207
+
2208
+ The integration also resolves `next.config.ts` rewrites. Static rewrite sources are matched exactly, while parameterized sources protect their safe static prefix. If a rewrite begins with a dynamic root segment, Geistdocs disables automatic recovery rather than risk returning a Markdown 404 for a real rewritten route.
2209
+
2210
+ No proxy option is required. Pass `markdownNotFound: false` only when the site needs to disable automatic recovery:
2211
+
2212
+ ```ts title="proxy.ts"
2213
+ const proxy = createProxy({
2214
+ config: geistdocsConfig,
2215
+ markdownNotFound: false,
2216
+ });
2217
+ ```
2218
+
2219
+ Existing sites that use `createMDX` directly do not receive a generated manifest and keep the previous opt-in behavior. Restart `next dev` after adding, deleting, or renaming a route; production builds always regenerate the manifest.
2220
+
2192
2221
  ## Hook context
2193
2222
 
2194
2223
  Both `before` and `after` receive the same context:
@@ -2282,7 +2311,6 @@ import { geistdocsSource } from "@/lib/geistdocs/source";
2282
2311
 
2283
2312
  export const { GET, generateStaticParams } =
2284
2313
  createDocsMarkdownRoute({
2285
- notFound: {},
2286
2314
  sources: [geistdocsSource],
2287
2315
  });
2288
2316
  ```
@@ -2306,7 +2334,7 @@ When a Markdown request does not match a page, Geistdocs returns an agent-readab
2306
2334
 
2307
2335
  For example, a request for `/docs/env-vars` can suggest `/docs/environment-variables.md`. The response uses a short cache lifetime and returns a real `404` status. It also sends `X-Robots-Tag: noindex` and no canonical link because the requested page does not exist. Regular HTML requests keep the app's standard not-found behavior.
2308
2336
 
2309
- Enable the suggestion response with `notFound: {}` on `createDocsMarkdownRoute`. Pass `notFound: { status: 410 }` for permanently removed pages. Legacy `status: 200` values are treated as `404` so missing pages always return a real error status. Without `notFound`, Markdown requests use the standard Next.js not-found response.
2337
+ The suggestion response is enabled by default. Pass `notFound: { status: 410 }` for permanently removed pages, or `notFound: false` to use the standard Next.js not-found response. Legacy `status: 200` values are treated as `404` so missing pages always return a real error status.
2310
2338
 
2311
2339
  If a custom `markdownRoutes` mapping changes the public path shape, set `notFound.getRequestedPath` to reconstruct the app-local public pathname. This also keeps page lookup and suggestions within the right source when a flattened route serves multiple sources:
2312
2340
 
@@ -2323,17 +2351,21 @@ Set `notFound.getPageMarkdownUrl` as well when suggested pages use a custom app-
2323
2351
 
2324
2352
  ### Unmatched application paths
2325
2353
 
2326
- Set `markdownNotFound: true` on `createProxy` only when every valid app page has a Markdown mapping. Unmapped Markdown or detected-agent requests then receive a concise 404 with links to the docs, `sitemap.md`, and `llms.txt`, while browser requests continue to the app's existing Next.js not-found UI.
2354
+ When `agent` is enabled, `createGeistdocs` scans App Router pages and route handlers during `next dev` and `next build`. `createProxy` uses that generated manifest to distinguish valid application routes from unknown paths. Valid routes continue to the app's HTML or route-handler response. Unknown Markdown or detected-agent `GET` and `HEAD` requests receive a concise 404 with links to the docs, `sitemap.md`, and `llms.txt`.
2327
2355
 
2328
- Sites with valid custom pages outside their Markdown mappings should pass a predicate instead. Return `false` for route families that should continue to Next.js:
2356
+ Markdown mappings take precedence over generated app routes, so a route that has both HTML and Markdown continues to negotiate Markdown. Dynamic app routes are treated as potentially valid; the app remains responsible for returning its own 404 when a specific slug does not exist.
2357
+
2358
+ Pass `markdownNotFound: false` to disable automatic unmatched-path recovery:
2329
2359
 
2330
2360
  ```ts title="proxy.ts"
2331
2361
  const proxy = createProxy({
2332
2362
  config: geistdocsConfig,
2333
- markdownNotFound: ({ pathname }) => !pathname.startsWith("/playground"),
2363
+ markdownNotFound: false,
2334
2364
  });
2335
2365
  ```
2336
2366
 
2367
+ Sites that do not use `createGeistdocs` keep the previous opt-in behavior. Existing boolean and predicate forms remain supported for compatibility.
2368
+
2337
2369
  `createNotFoundRoute` remains available for apps that prefer an explicit catch-all Route Handler with Geistdocs' minimal HTML response.
2338
2370
 
2339
2371
 
@@ -93,7 +93,7 @@
93
93
  "description": "Add custom request logic while keeping Geistdocs markdown negotiation in the package",
94
94
  "path": "pages/proxy.md",
95
95
  "source": "apps/template/content/docs/proxy.mdx",
96
- "summary": "Configure createProxy with before and after hooks, markdown route mappings, and a static Next.js matcher.",
96
+ "summary": "Configure createProxy with generated route discovery, request hooks, markdown mappings, and a static Next.js matcher.",
97
97
  "title": "Proxy and markdown routes",
98
98
  "type": "reference",
99
99
  "url": "/docs/proxy"
@@ -208,5 +208,5 @@
208
208
  }
209
209
  ],
210
210
  "source": "apps/template/content/docs",
211
- "version": "1.24.1"
211
+ "version": "1.25.1"
212
212
  }
@@ -27,6 +27,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
27
27
  | File | Purpose |
28
28
  | --- | --- |
29
29
  | `geistdocs.tsx` | Site-level settings, including logo, nav, GitHub repo, AI prompt, agent-readiness metadata, translations, and feature flags. |
30
+ | `next.config.ts` | Composes Fumadocs MDX, discovers App Router routes, and configures Next.js. |
30
31
  | `source.config.ts` | Configures Fumadocs collections with the package-provided schema, Markdown plugins, and syntax theme. |
31
32
  | `lib/geistdocs/config.tsx` | Converts `geistdocs.tsx` exports into the package config using `defineConfig`. |
32
33
  | `source.config.ts` | Configures Fumadocs collections with package-safe schemas and Markdown processing. |
@@ -216,11 +217,18 @@ To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/
216
217
  When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
217
218
 
218
219
  ```ts title="next.config.ts"
220
+ import { createGeistdocs } from "@vercel/geistdocs/next";
221
+ import type { NextConfig } from "next";
222
+
223
+ const withGeistdocs = createGeistdocs();
224
+
219
225
  const config: NextConfig = {
220
226
  basePath: "/docs",
221
227
  cacheComponents: true,
222
228
  partialPrefetching: true,
223
229
  };
230
+
231
+ export default withGeistdocs(config);
224
232
  ```
225
233
 
226
234
  ```tsx title="geistdocs.tsx"
package/docs/pages/md.md CHANGED
@@ -71,7 +71,6 @@ import { geistdocsSource } from "@/lib/geistdocs/source";
71
71
 
72
72
  export const { GET, generateStaticParams } =
73
73
  createDocsMarkdownRoute({
74
- notFound: {},
75
74
  sources: [geistdocsSource],
76
75
  });
77
76
  ```
@@ -95,7 +94,7 @@ When a Markdown request does not match a page, Geistdocs returns an agent-readab
95
94
 
96
95
  For example, a request for `/docs/env-vars` can suggest `/docs/environment-variables.md`. The response uses a short cache lifetime and returns a real `404` status. It also sends `X-Robots-Tag: noindex` and no canonical link because the requested page does not exist. Regular HTML requests keep the app's standard not-found behavior.
97
96
 
98
- Enable the suggestion response with `notFound: {}` on `createDocsMarkdownRoute`. Pass `notFound: { status: 410 }` for permanently removed pages. Legacy `status: 200` values are treated as `404` so missing pages always return a real error status. Without `notFound`, Markdown requests use the standard Next.js not-found response.
97
+ The suggestion response is enabled by default. Pass `notFound: { status: 410 }` for permanently removed pages, or `notFound: false` to use the standard Next.js not-found response. Legacy `status: 200` values are treated as `404` so missing pages always return a real error status.
99
98
 
100
99
  If a custom `markdownRoutes` mapping changes the public path shape, set `notFound.getRequestedPath` to reconstruct the app-local public pathname. This also keeps page lookup and suggestions within the right source when a flattened route serves multiple sources:
101
100
 
@@ -112,15 +111,19 @@ Set `notFound.getPageMarkdownUrl` as well when suggested pages use a custom app-
112
111
 
113
112
  ### Unmatched application paths
114
113
 
115
- Set `markdownNotFound: true` on `createProxy` only when every valid app page has a Markdown mapping. Unmapped Markdown or detected-agent requests then receive a concise 404 with links to the docs, `sitemap.md`, and `llms.txt`, while browser requests continue to the app's existing Next.js not-found UI.
114
+ When `agent` is enabled, `createGeistdocs` scans App Router pages and route handlers during `next dev` and `next build`. `createProxy` uses that generated manifest to distinguish valid application routes from unknown paths. Valid routes continue to the app's HTML or route-handler response. Unknown Markdown or detected-agent `GET` and `HEAD` requests receive a concise 404 with links to the docs, `sitemap.md`, and `llms.txt`.
116
115
 
117
- Sites with valid custom pages outside their Markdown mappings should pass a predicate instead. Return `false` for route families that should continue to Next.js:
116
+ Markdown mappings take precedence over generated app routes, so a route that has both HTML and Markdown continues to negotiate Markdown. Dynamic app routes are treated as potentially valid; the app remains responsible for returning its own 404 when a specific slug does not exist.
117
+
118
+ Pass `markdownNotFound: false` to disable automatic unmatched-path recovery:
118
119
 
119
120
  ```ts title="proxy.ts"
120
121
  const proxy = createProxy({
121
122
  config: geistdocsConfig,
122
- markdownNotFound: ({ pathname }) => !pathname.startsWith("/playground"),
123
+ markdownNotFound: false,
123
124
  });
124
125
  ```
125
126
 
127
+ Sites that do not use `createGeistdocs` keep the previous opt-in behavior. Existing boolean and predicate forms remain supported for compatibility.
128
+
126
129
  `createNotFoundRoute` remains available for apps that prefer an explicit catch-all Route Handler with Geistdocs' minimal HTML response.
@@ -58,24 +58,26 @@ If you are starting from a generated Geistdocs project and moving content into i
58
58
  pnpm dlx @vercel/geistdocs init --name my-docs
59
59
  ```
60
60
 
61
- ## Enable Cache Components
61
+ ## Configure Next.js
62
62
 
63
- Geistdocs uses Next.js Cache Components to prerender static application shells while dynamic content streams from the server. Enable Cache Components in `next.config.ts`:
63
+ The Geistdocs Next.js integration composes Fumadocs MDX, enables automatic app-route discovery for agent-readable 404s, and preserves your Next.js configuration. Enable Cache Components in the same file:
64
64
 
65
65
  ```ts title="next.config.ts"
66
- import { createMDX } from "fumadocs-mdx/next";
66
+ import { createGeistdocs } from "@vercel/geistdocs/next";
67
67
  import type { NextConfig } from "next";
68
68
 
69
- const withMDX = createMDX();
69
+ const withGeistdocs = createGeistdocs();
70
70
 
71
71
  const config: NextConfig = {
72
72
  cacheComponents: true,
73
73
  partialPrefetching: true,
74
74
  };
75
75
 
76
- export default withMDX(config);
76
+ export default withGeistdocs(config);
77
77
  ```
78
78
 
79
+ Restart `next dev` after adding, deleting, or renaming an App Router page or route. Production builds always regenerate the route manifest.
80
+
79
81
  Every root dynamic parameter needs at least one value from `generateStaticParams`. For a site with a `[lang]` root segment, return every configured language from the root layout:
80
82
 
81
83
  ```tsx title="app/[lang]/layout.tsx"
@@ -2,7 +2,7 @@
2
2
  title: Proxy and markdown routes
3
3
  description: Add custom request logic while keeping Geistdocs markdown negotiation in the package
4
4
  type: reference
5
- summary: Configure createProxy with before and after hooks, markdown route mappings, and a static Next.js matcher.
5
+ summary: Configure createProxy with generated route discovery, request hooks, markdown mappings, and a static Next.js matcher.
6
6
  url: /docs/proxy
7
7
  source: apps/template/content/docs/proxy.mdx
8
8
  prerequisites:
@@ -179,6 +179,25 @@ export const config = {
179
179
 
180
180
  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.
181
181
 
182
+ ## Recover unmatched Markdown requests
183
+
184
+ `createGeistdocs` in `next.config.ts` generates a lightweight manifest from App Router pages and route handlers. When `agent` is enabled, `createProxy` uses this manifest to return a Markdown 404 only when a `GET` or `HEAD` request matches neither a Markdown mapping nor an application route.
185
+
186
+ The manifest contains route patterns, not page modules or content. Static, dynamic, catch-all, optional catch-all, grouped, and localized routes continue to Next.js. Root catch-all pages are treated as potentially valid, so the app remains responsible for their 404 behavior. The package's own `[...not-found]` route handler is excluded so it does not claim every path.
187
+
188
+ The integration also resolves `next.config.ts` rewrites. Static rewrite sources are matched exactly, while parameterized sources protect their safe static prefix. If a rewrite begins with a dynamic root segment, Geistdocs disables automatic recovery rather than risk returning a Markdown 404 for a real rewritten route.
189
+
190
+ No proxy option is required. Pass `markdownNotFound: false` only when the site needs to disable automatic recovery:
191
+
192
+ ```ts title="proxy.ts"
193
+ const proxy = createProxy({
194
+ config: geistdocsConfig,
195
+ markdownNotFound: false,
196
+ });
197
+ ```
198
+
199
+ Existing sites that use `createMDX` directly do not receive a generated manifest and keep the previous opt-in behavior. Restart `next dev` after adding, deleting, or renaming a route; production builds always regenerate the manifest.
200
+
182
201
  ## Hook context
183
202
 
184
203
  Both `before` and `after` receive the same context:
package/docs/sitemap.md CHANGED
@@ -12,7 +12,7 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
12
12
  - [Syntax](pages/syntax.md) | URL: /docs/syntax | Type: reference | Summary: Supported MDX syntax including text formatting, code blocks, line highlighting, and Mermaid diagrams.
13
13
  - [Geistdocs Provider](pages/provider.md) | URL: /docs/provider | Type: reference | Summary: The root provider component that wraps your application to handle toast notifications, search, and analytics.
14
14
  - [Versioned docs](pages/versioned-docs.md) | URL: /docs/versioned-docs | Type: guide | Summary: Use createVersionedSources to configure stable, pre-release, or host-based documentation versions.
15
- - [Proxy and markdown routes](pages/proxy.md) | URL: /docs/proxy | Type: reference | Summary: Configure createProxy with before and after hooks, markdown route mappings, and a static Next.js matcher.
15
+ - [Proxy and markdown routes](pages/proxy.md) | URL: /docs/proxy | Type: reference | Summary: Configure createProxy with generated route discovery, request hooks, markdown mappings, and a static Next.js matcher.
16
16
  - [.md Extension](pages/md.md) | URL: /docs/md | Type: conceptual | Summary: Access any documentation page as raw Markdown by appending .md or .mdx to the URL for AI tool consumption.
17
17
  - [Agent readiness](pages/agent-readiness.md) | URL: /docs/agent-readiness | Type: guide | Summary: Generate /agents.md and /.well-known/mcp.json from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
18
18
  - [Ask AI](pages/ask-ai.md) | URL: /docs/ask-ai | Type: conceptual | Summary: An AI-powered chat assistant with context-aware search, persistent history, and suggested prompts for your documentation.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@vercel/geistdocs",
3
3
  "description": "Runtime and CLI for Geistdocs projects.",
4
- "version": "1.24.1",
4
+ "version": "1.25.1",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -110,6 +110,10 @@
110
110
  "types": "./dist/proxy.d.ts",
111
111
  "default": "./dist/proxy.js"
112
112
  },
113
+ "./next": {
114
+ "types": "./dist/next.d.ts",
115
+ "default": "./dist/next.js"
116
+ },
113
117
  "./mdx": {
114
118
  "types": "./dist/mdx.d.ts",
115
119
  "default": "./dist/mdx.js"
@@ -52,12 +52,14 @@ Use these instructions when an AI coding agent edits this project.
52
52
  ## Routing and proxy guidelines
53
53
 
54
54
  - Keep App Router route files as thin adapters around package helpers such as `createDocsPage`, `createChatRoute`, `createLlmsRoute`, and `createProxy`.
55
+ - Keep `createGeistdocs` from `@vercel/geistdocs/next` as the `next.config.ts` wrapper. It composes Fumadocs MDX and generates the app-route manifest used by `createProxy`; do not replace it with `createMDX` directly.
55
56
  - Keep `cacheComponents: true` and `partialPrefetching: true` in `next.config.ts`. Do not export `dynamic`, `revalidate`, or `fetchCache` from App Router pages or route handlers.
56
57
  - Read `[lang]` from `next/root-params` in Server Components. Keep route context `params` in Route Handlers and Server Actions.
57
58
  - Use `prefetch={true}` for app-owned links to fully static documentation pages so navigation does not stop at the generic route shell.
58
59
  - Keep `export const config` in `proxy.ts` as a static object. Next.js must parse proxy matchers at build time.
59
60
  - Use proxy matcher exclusions that only match `/api` and `/api/...`, such as `api(?:/|$)`. Do not exclude broad prefixes like `api`, because that also excludes routes such as `/api-reference`.
60
61
  - Preserve markdown negotiation unless the task explicitly changes AI-readable output. Geistdocs serves `/agents.md`, `/llms.txt`, `/.well-known/mcp.json`, and per-page Markdown for `.md`, `.mdx`, `Accept: text/markdown`, and AI-agent requests.
62
+ - Restart `next dev` after adding, deleting, or renaming an App Router page or route so `createGeistdocs` regenerates its route manifest.
61
63
  - When adding custom proxy behavior, prefer `before`, `after`, and `markdownRoutes` options on `createProxy` instead of replacing the proxy.
62
64
  - Use explicit `markdownRoutes` for root-mounted docs or any site where homepage/app routes coexist with docs routes.
63
65
  - Keep source URLs, navigation links, `getPageUrl`, and `markdownRoutes` app-local when `config.basePath` is set. Geistdocs derives public page-action and Markdown URLs separately.
@@ -2,6 +2,5 @@ import { createDocsMarkdownRoute } from "@vercel/geistdocs/routes/llms";
2
2
  import { geistdocsSource } from "@/lib/geistdocs/source";
3
3
 
4
4
  export const { GET, generateStaticParams } = createDocsMarkdownRoute({
5
- notFound: {},
6
5
  sources: [geistdocsSource],
7
6
  });
@@ -25,6 +25,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
25
25
  | File | Purpose |
26
26
  | --- | --- |
27
27
  | `geistdocs.tsx` | Site-level settings, including logo, nav, GitHub repo, AI prompt, agent-readiness metadata, translations, and feature flags. |
28
+ | `next.config.ts` | Composes Fumadocs MDX, discovers App Router routes, and configures Next.js. |
28
29
  | `source.config.ts` | Configures Fumadocs collections with the package-provided schema, Markdown plugins, and syntax theme. |
29
30
  | `lib/geistdocs/config.tsx` | Converts `geistdocs.tsx` exports into the package config using `defineConfig`. |
30
31
  | `source.config.ts` | Configures Fumadocs collections with package-safe schemas and Markdown processing. |
@@ -214,11 +215,18 @@ To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/
214
215
  When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
215
216
 
216
217
  ```ts title="next.config.ts"
218
+ import { createGeistdocs } from "@vercel/geistdocs/next";
219
+ import type { NextConfig } from "next";
220
+
221
+ const withGeistdocs = createGeistdocs();
222
+
217
223
  const config: NextConfig = {
218
224
  basePath: "/docs",
219
225
  cacheComponents: true,
220
226
  partialPrefetching: true,
221
227
  };
228
+
229
+ export default withGeistdocs(config);
222
230
  ```
223
231
 
224
232
  ```tsx title="geistdocs.tsx"
@@ -69,7 +69,6 @@ import { geistdocsSource } from "@/lib/geistdocs/source";
69
69
 
70
70
  export const { GET, generateStaticParams } =
71
71
  createDocsMarkdownRoute({
72
- notFound: {},
73
72
  sources: [geistdocsSource],
74
73
  });
75
74
  ```
@@ -93,7 +92,7 @@ When a Markdown request does not match a page, Geistdocs returns an agent-readab
93
92
 
94
93
  For example, a request for `/docs/env-vars` can suggest `/docs/environment-variables.md`. The response uses a short cache lifetime and returns a real `404` status. It also sends `X-Robots-Tag: noindex` and no canonical link because the requested page does not exist. Regular HTML requests keep the app's standard not-found behavior.
95
94
 
96
- Enable the suggestion response with `notFound: {}` on `createDocsMarkdownRoute`. Pass `notFound: { status: 410 }` for permanently removed pages. Legacy `status: 200` values are treated as `404` so missing pages always return a real error status. Without `notFound`, Markdown requests use the standard Next.js not-found response.
95
+ The suggestion response is enabled by default. Pass `notFound: { status: 410 }` for permanently removed pages, or `notFound: false` to use the standard Next.js not-found response. Legacy `status: 200` values are treated as `404` so missing pages always return a real error status.
97
96
 
98
97
  If a custom `markdownRoutes` mapping changes the public path shape, set `notFound.getRequestedPath` to reconstruct the app-local public pathname. This also keeps page lookup and suggestions within the right source when a flattened route serves multiple sources:
99
98
 
@@ -110,15 +109,19 @@ Set `notFound.getPageMarkdownUrl` as well when suggested pages use a custom app-
110
109
 
111
110
  ### Unmatched application paths
112
111
 
113
- Set `markdownNotFound: true` on `createProxy` only when every valid app page has a Markdown mapping. Unmapped Markdown or detected-agent requests then receive a concise 404 with links to the docs, `sitemap.md`, and `llms.txt`, while browser requests continue to the app's existing Next.js not-found UI.
112
+ When `agent` is enabled, `createGeistdocs` scans App Router pages and route handlers during `next dev` and `next build`. `createProxy` uses that generated manifest to distinguish valid application routes from unknown paths. Valid routes continue to the app's HTML or route-handler response. Unknown Markdown or detected-agent `GET` and `HEAD` requests receive a concise 404 with links to the docs, `sitemap.md`, and `llms.txt`.
114
113
 
115
- Sites with valid custom pages outside their Markdown mappings should pass a predicate instead. Return `false` for route families that should continue to Next.js:
114
+ Markdown mappings take precedence over generated app routes, so a route that has both HTML and Markdown continues to negotiate Markdown. Dynamic app routes are treated as potentially valid; the app remains responsible for returning its own 404 when a specific slug does not exist.
115
+
116
+ Pass `markdownNotFound: false` to disable automatic unmatched-path recovery:
116
117
 
117
118
  ```ts title="proxy.ts"
118
119
  const proxy = createProxy({
119
120
  config: geistdocsConfig,
120
- markdownNotFound: ({ pathname }) => !pathname.startsWith("/playground"),
121
+ markdownNotFound: false,
121
122
  });
122
123
  ```
123
124
 
125
+ Sites that do not use `createGeistdocs` keep the previous opt-in behavior. Existing boolean and predicate forms remain supported for compatibility.
126
+
124
127
  `createNotFoundRoute` remains available for apps that prefer an explicit catch-all Route Handler with Geistdocs' minimal HTML response.
@@ -56,24 +56,26 @@ If you are starting from a generated Geistdocs project and moving content into i
56
56
  pnpm dlx @vercel/geistdocs init --name my-docs
57
57
  ```
58
58
 
59
- ## Enable Cache Components
59
+ ## Configure Next.js
60
60
 
61
- Geistdocs uses Next.js Cache Components to prerender static application shells while dynamic content streams from the server. Enable Cache Components in `next.config.ts`:
61
+ The Geistdocs Next.js integration composes Fumadocs MDX, enables automatic app-route discovery for agent-readable 404s, and preserves your Next.js configuration. Enable Cache Components in the same file:
62
62
 
63
63
  ```ts title="next.config.ts"
64
- import { createMDX } from "fumadocs-mdx/next";
64
+ import { createGeistdocs } from "@vercel/geistdocs/next";
65
65
  import type { NextConfig } from "next";
66
66
 
67
- const withMDX = createMDX();
67
+ const withGeistdocs = createGeistdocs();
68
68
 
69
69
  const config: NextConfig = {
70
70
  cacheComponents: true,
71
71
  partialPrefetching: true,
72
72
  };
73
73
 
74
- export default withMDX(config);
74
+ export default withGeistdocs(config);
75
75
  ```
76
76
 
77
+ Restart `next dev` after adding, deleting, or renaming an App Router page or route. Production builds always regenerate the route manifest.
78
+
77
79
  Every root dynamic parameter needs at least one value from `generateStaticParams`. For a site with a `[lang]` root segment, return every configured language from the root layout:
78
80
 
79
81
  ```tsx title="app/[lang]/layout.tsx"