@vercel/geistdocs 1.22.0 → 1.23.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 (71) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +2 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/footer.d.ts.map +1 -1
  5. package/dist/footer.js +5 -0
  6. package/dist/home-layout.d.ts +2 -2
  7. package/dist/home-layout.d.ts.map +1 -1
  8. package/dist/home-layout.js +52 -18
  9. package/dist/internal/localized-link.js +1 -1
  10. package/dist/internal/navbar/navbar-logo.d.ts.map +1 -1
  11. package/dist/internal/navbar/navbar-logo.js +27 -7
  12. package/dist/internal/page-actions-client.d.ts.map +1 -1
  13. package/dist/internal/page-actions-client.js +18 -2
  14. package/dist/internal/ui/navigation-menu.d.ts +1 -1
  15. package/dist/internal/ui/navigation-menu.d.ts.map +1 -1
  16. package/dist/internal/ui/navigation-menu.js +2 -9
  17. package/dist/localize-href.d.ts +6 -0
  18. package/dist/localize-href.d.ts.map +1 -0
  19. package/dist/{internal/localize-href.js → localize-href.js} +2 -5
  20. package/dist/{internal/page-visibility.d.ts → page-visibility.d.ts} +1 -1
  21. package/dist/page-visibility.d.ts.map +1 -0
  22. package/dist/pages/docs.d.ts +2 -2
  23. package/dist/pages/docs.d.ts.map +1 -1
  24. package/dist/pages/docs.js +10 -5
  25. package/dist/proxy.d.ts +1 -1
  26. package/dist/proxy.d.ts.map +1 -1
  27. package/dist/proxy.js +13 -2
  28. package/dist/routes/agents.d.ts.map +1 -1
  29. package/dist/routes/agents.js +4 -4
  30. package/dist/routes/chat.js +1 -1
  31. package/dist/routes/llms.js +1 -1
  32. package/dist/routes/not-found.d.ts +14 -0
  33. package/dist/routes/not-found.d.ts.map +1 -0
  34. package/dist/routes/not-found.js +74 -0
  35. package/dist/routes/search.js +1 -1
  36. package/dist/routes/sitemap.d.ts +1 -1
  37. package/dist/routes/sitemap.d.ts.map +1 -1
  38. package/dist/routes/sitemap.js +1 -1
  39. package/docs/agents.md +1 -1
  40. package/docs/llms.txt +8 -4
  41. package/docs/manifest.json +1 -1
  42. package/docs/pages/agent-readiness.md +1 -1
  43. package/docs/pages/env.md +2 -2
  44. package/docs/pages/md.md +2 -0
  45. package/docs/pages/proxy.md +2 -0
  46. package/package.json +13 -1
  47. package/template/app/[lang]/(home)/components/centered-section.tsx +9 -1
  48. package/template/app/[lang]/(home)/components/text-grid-section.tsx +39 -10
  49. package/template/app/[lang]/(home)/opengraph-image.tsx +40 -0
  50. package/template/app/[lang]/(home)/page.tsx +145 -89
  51. package/template/app/[lang]/[...not-found]/route.ts +4 -0
  52. package/template/app/[lang]/layout.tsx +7 -0
  53. package/template/app/[lang]/not-found.tsx +37 -0
  54. package/template/app/[lang]/rss.xml/route.ts +3 -4
  55. package/template/app/robots.ts +4 -4
  56. package/template/app/sitemap.ts +11 -8
  57. package/template/content/docs/agent-readiness.mdx +1 -1
  58. package/template/content/docs/env.mdx +2 -2
  59. package/template/content/docs/md.mdx +2 -0
  60. package/template/content/docs/proxy.mdx +2 -0
  61. package/template/lib/geistdocs/config.tsx +2 -0
  62. package/template/lib/geistdocs/public-path.ts +14 -0
  63. package/template/lib/geistdocs/site-url-warning.ts +10 -0
  64. package/template/lib/geistdocs/site-url.ts +33 -0
  65. package/template/next.config.ts +0 -10
  66. package/template/package.json +1 -1
  67. package/dist/internal/localize-href.d.ts +0 -9
  68. package/dist/internal/localize-href.d.ts.map +0 -1
  69. package/dist/internal/page-visibility.d.ts.map +0 -1
  70. package/template/app/[lang]/(home)/components/templates.tsx +0 -48
  71. /package/dist/{internal/page-visibility.js → page-visibility.js} +0 -0
@@ -4,7 +4,7 @@ const getDefaultAgentInstructions = (config) => [
4
4
  `Use ${getPublicPath("/sitemap.md", config.basePath)} to identify the most relevant documentation pages before answering broad questions.`,
5
5
  `Use ${getPublicPath("/llms.txt", config.basePath)} when you need the complete documentation corpus as Markdown context.`,
6
6
  "Fetch individual documentation pages with a .md or .mdx extension for focused page-level context.",
7
- "Do not assume API, authentication, OpenAPI, or MCP support unless it is listed in this file.",
7
+ "Only use product capabilities and integration surfaces that are explicitly listed in this file.",
8
8
  ];
9
9
  const escapeMarkdown = (value) => value.replace(/([\\[\]])/g, "\\$1");
10
10
  const renderLink = (label, href, description) => {
@@ -65,11 +65,11 @@ const renderDocumentationSection = (config, origin) => [
65
65
  "- Page-level Markdown: append .md or .mdx to a documentation URL",
66
66
  "",
67
67
  ];
68
- const renderProductSection = (product = {}) => {
68
+ const renderProductSection = (productName, product = {}) => {
69
69
  if (!(product.category || product.audience?.length || product.useCases?.length)) {
70
70
  return [];
71
71
  }
72
- const lines = ["## Product Context", ""];
72
+ const lines = [`## When to use ${productName}`, ""];
73
73
  if (product.category) {
74
74
  lines.push(`- Category: ${product.category}`);
75
75
  }
@@ -184,7 +184,7 @@ const renderAgentsMarkdown = (config, request) => {
184
184
  "This file helps AI agents understand and use this documentation site.",
185
185
  "",
186
186
  ...renderDocumentationSection(config, origin),
187
- ...renderProductSection(product),
187
+ ...renderProductSection(name, product),
188
188
  ...renderApiSection(agent.api, config, origin),
189
189
  ...renderMcpSection(agent.mcp, config, origin),
190
190
  ...renderImportantLinksSection(agent, config, origin),
@@ -4,7 +4,7 @@ import { initAdvancedSearch } from "fumadocs-core/search/server";
4
4
  import { z } from "zod";
5
5
  import { getPublicPath } from "../config";
6
6
  import { buildEveAgentTranscript, capLastUserMessageText, getEveAgentSessionHandle, resolveEveAgentUrl, runEveAgentTurn, } from "../internal/eve-agent";
7
- import { isPageVisibleForSurface } from "../internal/page-visibility";
7
+ import { isPageVisibleForSurface } from "../page-visibility";
8
8
  const DEFAULT_CHAT_MODEL = "openai/gpt-4.1-mini";
9
9
  const MAX_CONTEXT_CHARS = 1500;
10
10
  const MAX_EVE_AGENT_MESSAGE_CHARS = 4000;
@@ -2,8 +2,8 @@ import { applyMarkdownHeaders, createNotFoundResponse, } from "@vercel/agent-rea
2
2
  import { notFound } from "next/navigation";
3
3
  import { getPublicPath, normalizeBasePath, withBasePath, } from "../config.js";
4
4
  import { resolvePageMarkdownUrl } from "../internal/markdown-url.js";
5
- import { isPageVisibleForSurface } from "../internal/page-visibility.js";
6
5
  import { findSmartNotFoundSuggestions, renderSmartNotFoundMarkdown, } from "../internal/smart-not-found.js";
6
+ import { isPageVisibleForSurface } from "../page-visibility.js";
7
7
  const INDEX_MARKDOWN_PATTERN = /\/index\.md$/;
8
8
  const MARKDOWN_PATTERN = /\.md$/;
9
9
  const resolveSources = (source, sources, caller) => {
@@ -0,0 +1,14 @@
1
+ import type { NextRequest } from "next/server";
2
+ import { type GeistdocsConfig } from "../config";
3
+ interface CreateNotFoundRouteOptions {
4
+ config: Pick<GeistdocsConfig, "basePath" | "defaultLanguage" | "translations">;
5
+ }
6
+ export declare const createNotFoundRoute: ({ config }: CreateNotFoundRouteOptions) => {
7
+ GET: (request: NextRequest, { params }: {
8
+ params: Promise<{
9
+ lang?: string;
10
+ }>;
11
+ }) => Promise<Response>;
12
+ };
13
+ export {};
14
+ //# sourceMappingURL=not-found.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"not-found.d.ts","sourceRoot":"","sources":["../../src/routes/not-found.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,WAAW,CAAC;AAGhE,UAAU,0BAA0B;IAClC,MAAM,EAAE,IAAI,CACV,eAAe,EACf,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAChD,CAAC;CACH;AASD,eAAO,MAAM,mBAAmB,GAAI,YAAY,0BAA0B;mBAE7D,WAAW,cACR;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;CAsErD,CAAC"}
@@ -0,0 +1,74 @@
1
+ import { createNotFoundResponse, isAIAgent } from "@vercel/agent-readability";
2
+ import { isMarkdownPreferred } from "fumadocs-core/negotiation";
3
+ import { getPublicPath } from "../config";
4
+ import { localizeHref } from "../localize-href";
5
+ const escapeHtml = (value) => value
6
+ .replaceAll("&", "&amp;")
7
+ .replaceAll('"', "&quot;")
8
+ .replaceAll("<", "&lt;")
9
+ .replaceAll(">", "&gt;");
10
+ export const createNotFoundRoute = ({ config }) => {
11
+ const GET = async (request, { params }) => {
12
+ const { lang: requestedLanguage } = await params;
13
+ const defaultLanguage = config.defaultLanguage ?? "en";
14
+ const supportedLanguages = new Set([
15
+ defaultLanguage,
16
+ ...Object.keys(config.translations ?? {}),
17
+ ]);
18
+ const lang = requestedLanguage && supportedLanguages.has(requestedLanguage)
19
+ ? requestedLanguage
20
+ : defaultLanguage;
21
+ const publicPath = (path) => getPublicPath(localizeHref(path, lang, defaultLanguage), config.basePath);
22
+ const docsUrl = publicPath("/docs");
23
+ const sitemapUrl = publicPath("/sitemap.md");
24
+ const llmsUrl = publicPath("/llms.txt");
25
+ const vary = "Accept, User-Agent, Signature-Agent";
26
+ if (isMarkdownPreferred(request) || isAIAgent(request).detected) {
27
+ return createNotFoundResponse(request.nextUrl.pathname, {
28
+ headers: {
29
+ "Cache-Control": "private, no-store",
30
+ Vary: vary,
31
+ },
32
+ markdown: `# Page Not Found
33
+
34
+ The requested page does not exist.
35
+
36
+ - [Browse the documentation](${docsUrl})
37
+ - [Open the semantic sitemap](${sitemapUrl})
38
+ - [Open the complete Markdown corpus](${llmsUrl})
39
+ `,
40
+ });
41
+ }
42
+ const html = `<!doctype html>
43
+ <html lang="${escapeHtml(lang)}">
44
+ <head>
45
+ <meta charset="utf-8">
46
+ <meta name="robots" content="noindex">
47
+ <meta name="viewport" content="width=device-width, initial-scale=1">
48
+ <title>Page not found</title>
49
+ </head>
50
+ <body>
51
+ <main>
52
+ <p>404</p>
53
+ <h1>Page not found</h1>
54
+ <p>The requested page does not exist. Use one of these indexes to find the closest current page.</p>
55
+ <ul>
56
+ <li><a href="${escapeHtml(docsUrl)}">Browse the documentation</a></li>
57
+ <li><a href="${escapeHtml(sitemapUrl)}">Open the semantic sitemap</a></li>
58
+ <li><a href="${escapeHtml(llmsUrl)}">Open the complete Markdown corpus</a></li>
59
+ </ul>
60
+ </main>
61
+ </body>
62
+ </html>`;
63
+ return new Response(html, {
64
+ headers: {
65
+ "Cache-Control": "private, no-store",
66
+ "Content-Type": "text/html; charset=utf-8",
67
+ Vary: vary,
68
+ "X-Robots-Tag": "noindex",
69
+ },
70
+ status: 404,
71
+ });
72
+ };
73
+ return { GET };
74
+ };
@@ -3,7 +3,7 @@ import { createTokenizer as createTokenizerMandarin } from "@orama/tokenizers/ma
3
3
  import { defineI18n } from "fumadocs-core/i18n";
4
4
  import { findPath } from "fumadocs-core/page-tree";
5
5
  import { createI18nSearchAPI, } from "fumadocs-core/search/server";
6
- import { isPageVisibleForSurface } from "../internal/page-visibility";
6
+ import { isPageVisibleForSurface } from "../page-visibility";
7
7
  import { isGeistdocsSourceBundle } from "../source";
8
8
  const getLanguages = (config) => {
9
9
  const defaultLanguage = config.defaultLanguage ?? "en";
@@ -1,6 +1,6 @@
1
1
  import type { NextRequest } from "next/server";
2
2
  import { type GeistdocsConfig } from "../config";
3
- import { type GeistdocsPageVisibilityData } from "../internal/page-visibility";
3
+ import { type GeistdocsPageVisibilityData } from "../page-visibility";
4
4
  import { type GeistdocsSourceBundle } from "../source";
5
5
  interface SitemapPage {
6
6
  data: {
@@ -1 +1 @@
1
- {"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../src/routes/sitemap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,WAAW,CAAC;AAChE,OAAO,EACL,KAAK,2BAA2B,EAEjC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,KAAK,qBAAqB,EAA2B,MAAM,WAAW,CAAC;AAKhF,UAAU,WAAW;IACnB,IAAI,EAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,IAAI,CAAC;KACrB,GAAG,2BAA2B,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;CACvC;AAED,KAAK,kBAAkB,GAAG,qBAAqB,GAAG,aAAa,CAAC;AAEhE,UAAU,cAAc;IACtB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,iCAAiC;IACzC,MAAM,EAAE,IAAI,CACV,eAAe,EACf,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAChD,CAAC;IACF,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,CACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KACtB,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CAC/B;AAuMD,eAAO,MAAM,0BAA0B,GAAI,gDAMxC,iCAAiC;gBAK1B,WAAW,cACL;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;;;;;;CA4DpD,CAAC"}
1
+ {"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../src/routes/sitemap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,WAAW,CAAC;AAChE,OAAO,EACL,KAAK,2BAA2B,EAEjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,qBAAqB,EAA2B,MAAM,WAAW,CAAC;AAKhF,UAAU,WAAW;IACnB,IAAI,EAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,IAAI,CAAC;KACrB,GAAG,2BAA2B,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;CACvC;AAED,KAAK,kBAAkB,GAAG,qBAAqB,GAAG,aAAa,CAAC;AAEhE,UAAU,cAAc;IACtB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,iCAAiC;IACzC,MAAM,EAAE,IAAI,CACV,eAAe,EACf,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAChD,CAAC;IACF,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,CACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KACtB,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CAC/B;AAuMD,eAAO,MAAM,0BAA0B,GAAI,gDAMxC,iCAAiC;gBAK1B,WAAW,cACL;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;;;;;;CA4DpD,CAAC"}
@@ -1,5 +1,5 @@
1
1
  import { getPublicPath } from "../config";
2
- import { isPageVisibleForSurface, } from "../internal/page-visibility";
2
+ import { isPageVisibleForSurface, } from "../page-visibility";
3
3
  import { isGeistdocsSourceBundle } from "../source";
4
4
  const DOCS_PREFIX_PATTERN = /^\/docs\/?/;
5
5
  const WHITESPACE_PATTERN = /\s+/;
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.22.0 so agents can understand the installed package without web access.
3
+ These docs are bundled with `@vercel/geistdocs` 1.23.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
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.22.0.
3
+ These docs are bundled with `@vercel/geistdocs` 1.23.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
@@ -314,9 +314,9 @@ The Vertex deployment does not need a Geistdocs-specific environment variable. A
314
314
 
315
315
  ## `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`
316
316
 
317
- The production URL of the Geistdocs site. This is automatically set when deploying to Vercel.
317
+ The production URL of the Geistdocs site. Geistdocs uses it for canonical and Open Graph metadata, product JSON-LD, `sitemap.xml`, `robots.txt`, and RSS links. Vercel sets this variable automatically.
318
318
 
319
- It should be in the format `localhost:3000` (i.e. without the protocol prefix). This is how Vercel sets the environment variable when deploying to a project.
319
+ Set this variable explicitly when deploying outside Vercel. Use a hostname such as `docs.example.com` or a full `http` or `https` URL. Local development falls back to `http://localhost:3000`. A production build with a missing or malformed value emits a warning and omits default canonical and product JSON-LD URLs. Its `sitemap.xml`, `robots.txt` sitemap directive, RSS links, and generated Open Graph image URLs continue to use the localhost fallback, so treat the warning as a deployment blocker. Geistdocs does not use the deployment-specific `VERCEL_URL` for canonical surfaces.
320
320
 
321
321
 
322
322
  ---
@@ -2099,6 +2099,8 @@ const proxy = createProxy({
2099
2099
 
2100
2100
  Define `content` sections in `lib/geistdocs/config.tsx` to infer standard Markdown route mappings from each section route. The package still serves `/llms.txt` and individual page Markdown through route helpers; the proxy uses these mappings for `.md`, `.mdx`, `Accept: text/markdown`, and AI-agent requests.
2101
2101
 
2102
+ When `agent` metadata is configured, a request to the homepage with `Accept: text/markdown` returns the generated `/agents.md` content. This gives agents a product overview and focused discovery links without treating every application route as documentation.
2103
+
2102
2104
  Geistdocs does not infer Markdown mappings for `content` sections with `route: "/"`. A root catch-all such as `/*path` can make a homepage or other application routes look like documentation. Use explicit `markdownRoutes` for root-mounted docs.
2103
2105
 
2104
2106
  ```tsx title="lib/geistdocs/config.tsx"
@@ -2304,6 +2306,8 @@ When a Markdown request does not match a page, Geistdocs returns an agent-readab
2304
2306
 
2305
2307
  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.
2306
2308
 
2309
+ Generated projects also include a catch-all route for unknown application paths outside configured documentation sections. It returns a concise Markdown 404 with links to the docs, `sitemap.md`, and `llms.txt` for agent or `Accept: text/markdown` requests. Browser requests receive the same recovery links as HTML.
2310
+
2307
2311
  Enable this behavior with `notFound: {}`. 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.
2308
2312
 
2309
2313
  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:
@@ -2343,7 +2347,7 @@ Geistdocs can generate `/agents.md` and `/.well-known/mcp.json` discovery files
2343
2347
 
2344
2348
  ## What it provides
2345
2349
 
2346
- The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. The optional `/.well-known/mcp.json` route advertises configured MCP servers without running an MCP server inside Geistdocs.
2350
+ The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. Its product section states when to use the documented product, and the homepage serves the same guidance when an agent requests `text/markdown`. The optional `/.well-known/mcp.json` route advertises configured MCP servers without running an MCP server inside Geistdocs.
2347
2351
 
2348
2352
  It can include:
2349
2353
 
@@ -208,5 +208,5 @@
208
208
  }
209
209
  ],
210
210
  "source": "apps/template/content/docs",
211
- "version": "1.22.0"
211
+ "version": "1.23.1"
212
212
  }
@@ -19,7 +19,7 @@ Geistdocs can generate `/agents.md` and `/.well-known/mcp.json` discovery files
19
19
 
20
20
  ## What it provides
21
21
 
22
- The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. The optional `/.well-known/mcp.json` route advertises configured MCP servers without running an MCP server inside Geistdocs.
22
+ The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. Its product section states when to use the documented product, and the homepage serves the same guidance when an agent requests `text/markdown`. The optional `/.well-known/mcp.json` route advertises configured MCP servers without running an MCP server inside Geistdocs.
23
23
 
24
24
  It can include:
25
25
 
package/docs/pages/env.md CHANGED
@@ -57,6 +57,6 @@ The Vertex deployment does not need a Geistdocs-specific environment variable. A
57
57
 
58
58
  ## `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL`
59
59
 
60
- The production URL of the Geistdocs site. This is automatically set when deploying to Vercel.
60
+ The production URL of the Geistdocs site. Geistdocs uses it for canonical and Open Graph metadata, product JSON-LD, `sitemap.xml`, `robots.txt`, and RSS links. Vercel sets this variable automatically.
61
61
 
62
- It should be in the format `localhost:3000` (i.e. without the protocol prefix). This is how Vercel sets the environment variable when deploying to a project.
62
+ Set this variable explicitly when deploying outside Vercel. Use a hostname such as `docs.example.com` or a full `http` or `https` URL. Local development falls back to `http://localhost:3000`. A production build with a missing or malformed value emits a warning and omits default canonical and product JSON-LD URLs. Its `sitemap.xml`, `robots.txt` sitemap directive, RSS links, and generated Open Graph image URLs continue to use the localhost fallback, so treat the warning as a deployment blocker. Geistdocs does not use the deployment-specific `VERCEL_URL` for canonical surfaces.
package/docs/pages/md.md CHANGED
@@ -95,6 +95,8 @@ When a Markdown request does not match a page, Geistdocs returns an agent-readab
95
95
 
96
96
  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
97
 
98
+ Generated projects also include a catch-all route for unknown application paths outside configured documentation sections. It returns a concise Markdown 404 with links to the docs, `sitemap.md`, and `llms.txt` for agent or `Accept: text/markdown` requests. Browser requests receive the same recovery links as HTML.
99
+
98
100
  Enable this behavior with `notFound: {}`. 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.
99
101
 
100
102
  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:
@@ -89,6 +89,8 @@ const proxy = createProxy({
89
89
 
90
90
  Define `content` sections in `lib/geistdocs/config.tsx` to infer standard Markdown route mappings from each section route. The package still serves `/llms.txt` and individual page Markdown through route helpers; the proxy uses these mappings for `.md`, `.mdx`, `Accept: text/markdown`, and AI-agent requests.
91
91
 
92
+ When `agent` metadata is configured, a request to the homepage with `Accept: text/markdown` returns the generated `/agents.md` content. This gives agents a product overview and focused discovery links without treating every application route as documentation.
93
+
92
94
  Geistdocs does not infer Markdown mappings for `content` sections with `route: "/"`. A root catch-all such as `/*path` can make a homepage or other application routes look like documentation. Use explicit `markdownRoutes` for root-mounted docs.
93
95
 
94
96
  ```tsx title="lib/geistdocs/config.tsx"
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.22.0",
4
+ "version": "1.23.1",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -34,10 +34,18 @@
34
34
  "types": "./dist/layout.d.ts",
35
35
  "default": "./dist/layout.js"
36
36
  },
37
+ "./localize-href": {
38
+ "types": "./dist/localize-href.d.ts",
39
+ "default": "./dist/localize-href.js"
40
+ },
37
41
  "./navbar": {
38
42
  "types": "./dist/navbar.d.ts",
39
43
  "default": "./dist/navbar.js"
40
44
  },
45
+ "./page-visibility": {
46
+ "types": "./dist/page-visibility.d.ts",
47
+ "default": "./dist/page-visibility.js"
48
+ },
41
49
  "./footer": {
42
50
  "types": "./dist/footer.d.ts",
43
51
  "default": "./dist/footer.js"
@@ -94,6 +102,10 @@
94
102
  "types": "./dist/routes/mcp.d.ts",
95
103
  "default": "./dist/routes/mcp.js"
96
104
  },
105
+ "./routes/not-found": {
106
+ "types": "./dist/routes/not-found.d.ts",
107
+ "default": "./dist/routes/not-found.js"
108
+ },
97
109
  "./proxy": {
98
110
  "types": "./dist/proxy.d.ts",
99
111
  "default": "./dist/proxy.js"
@@ -1,18 +1,26 @@
1
1
  import type { ReactNode } from "react";
2
2
 
3
3
  interface CenteredSectionProps {
4
+ align?: "center" | "left";
4
5
  children: ReactNode;
5
6
  description: string;
6
7
  title: string;
7
8
  }
8
9
 
9
10
  export const CenteredSection = ({
11
+ align = "center",
10
12
  title,
11
13
  description,
12
14
  children,
13
15
  }: CenteredSectionProps) => (
14
16
  <div className="grid items-center gap-10 overflow-hidden @min-[640px]:py-12 py-8">
15
- <div className="mx-auto grid max-w-lg gap-4 text-center">
17
+ <div
18
+ className={
19
+ align === "left"
20
+ ? "grid max-w-3xl gap-4"
21
+ : "mx-auto grid max-w-lg gap-4 text-center"
22
+ }
23
+ >
16
24
  <h2 className="font-[450]! @min-[1024px]:text-[40px] @min-[640px]:text-2xl @min-[768px]:text-3xl text-gray-1000 text-xl tracking-tighter">
17
25
  {title}
18
26
  </h2>
@@ -1,20 +1,49 @@
1
+ import { cn } from "@/lib/utils";
2
+
1
3
  interface TextGridSectionProps {
4
+ className?: string;
2
5
  data: {
3
6
  id: string;
4
7
  title: string;
5
8
  description: string;
6
9
  }[];
10
+ description?: string;
11
+ title?: string;
7
12
  }
8
13
 
9
- export const TextGridSection = ({ data }: TextGridSectionProps) => (
10
- <div className="grid @min-[768px]:grid-cols-4 gap-8 @min-[640px]:py-12 py-8">
11
- {data.map((item) => (
12
- <div key={item.id}>
13
- <h3 className="mb-2 font-[450] text-gray-1000 text-heading-20 tracking-tight">
14
- {item.title}
15
- </h3>
16
- <p className="text-copy-16 text-gray-900">{item.description}</p>
14
+ export const TextGridSection = ({
15
+ className,
16
+ data,
17
+ description,
18
+ title,
19
+ }: TextGridSectionProps) => (
20
+ <section
21
+ className={cn(
22
+ "grid @min-[640px]:gap-16 gap-12 @min-[640px]:py-12 py-8",
23
+ className
24
+ )}
25
+ >
26
+ {title || description ? (
27
+ <div className="grid max-w-3xl gap-2 text-balance">
28
+ {title ? (
29
+ <h2 className="font-[450]! @min-[1024px]:text-[40px] @min-[640px]:text-2xl @min-[768px]:text-3xl text-gray-1000 text-xl tracking-tighter">
30
+ {title}
31
+ </h2>
32
+ ) : null}
33
+ {description ? (
34
+ <p className="text-gray-900 text-lg">{description}</p>
35
+ ) : null}
17
36
  </div>
18
- ))}
19
- </div>
37
+ ) : null}
38
+ <div className="grid @min-[768px]:grid-cols-4 gap-8">
39
+ {data.map((item) => (
40
+ <div key={item.id}>
41
+ <h3 className="mb-2 font-[450] text-gray-1000 text-heading-20 tracking-tight">
42
+ {item.title}
43
+ </h3>
44
+ <p className="text-copy-16 text-gray-900">{item.description}</p>
45
+ </div>
46
+ ))}
47
+ </div>
48
+ </section>
20
49
  );
@@ -0,0 +1,40 @@
1
+ import { ImageResponse } from "next/og";
2
+
3
+ export const alt = "Geistdocs documentation platform";
4
+ export const contentType = "image/png";
5
+ export const size = {
6
+ height: 630,
7
+ width: 1200,
8
+ };
9
+
10
+ const OpenGraphImage = () =>
11
+ new ImageResponse(
12
+ <div
13
+ style={{
14
+ alignItems: "center",
15
+ background: "#000",
16
+ color: "#fff",
17
+ display: "flex",
18
+ height: "100%",
19
+ justifyContent: "center",
20
+ width: "100%",
21
+ }}
22
+ >
23
+ <div
24
+ style={{
25
+ display: "flex",
26
+ flexDirection: "column",
27
+ gap: 24,
28
+ maxWidth: 920,
29
+ }}
30
+ >
31
+ <div style={{ fontSize: 76, fontWeight: 600 }}>Geistdocs</div>
32
+ <div style={{ color: "#a1a1a1", fontSize: 36, lineHeight: 1.25 }}>
33
+ Package-backed documentation sites for people and agents
34
+ </div>
35
+ </div>
36
+ </div>,
37
+ size
38
+ );
39
+
40
+ export default OpenGraphImage;