jamdesk 1.1.199 → 1.1.200

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.199",
+  "version": "1.1.200",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",

package/vendored/lib/render-doc-page.tsx

@@ -348,6 +348,79 @@ export async function resolveOpenApiMetaDescription(
   return null;
 }
 
+/**
+ * The description used for `<meta>`, the OG/Twitter tags and the OG card
+ * image: authored frontmatter first, then the OpenAPI operation, then the
+ * page's first prose paragraph.
+ *
+ * Shared by `buildDocMetadata` and `renderDocPage` so the meta tags and the
+ * JSON-LD `image` resolve the SAME text. They used to disagree: only the
+ * metadata path resolved a description, so on pages with none authored the
+ * JSON-LD card URL omitted `description=` while og:image carried it, and the
+ * two URLs rendered two genuinely different cards — two OG renders and two CDN
+ * entries per page.
+ *
+ * The gate stays on the RAW value, not frontmatterText(): YAML hands back a
+ * Date for `description: 2026-01-01` and a number for `description: 404`.
+ * Both are truthy and must keep suppressing the fallbacks exactly as before.
+ *
+ * NEVER write the result back onto `data`. `parseFrontmatter` is gray-matter,
+ * whose cache returns a shallow copy that SHARES one `data` object per content
+ * string (gray-matter/index.js:39, `Object.assign({}, cached)`), so an
+ * assignment reached `renderDocPage`'s own parse of the same page and rendered
+ * as the page SUBTITLE: the operation description twice on every spec-backed
+ * page, and the first paragraph twice on every description-less prose page.
+ * The cache is module-global, so it persisted across requests rather than
+ * being a within-request ordering race. (#7 follow-up.)
+ */
+export async function resolveDerivedDescription(
+  config: DocsConfig,
+  data: FrontmatterData,
+  content: string,
+  projectSlug: string | null | undefined,
+): Promise<string | undefined> {
+  let metaDescription: string | undefined = data.description;
+  if (metaDescription) return metaDescription;
+
+  if (typeof data.openapi === 'string' && data.openapi && config.api?.openapi) {
+    // Source the description from the OpenAPI operation before falling back to
+    // first-paragraph extraction (which is empty for prose-less API pages).
+    // The spec loader REUSES the render path's cached loaders — the ISR module
+    // cache (`r2:${slug}:${specPath}`, 10-min TTL) that `renderDocPage`
+    // populates when it renders the page's <ApiEndpoint>, or the static
+    // `getCachedSpec`. So the spec is the same warm parse the render already
+    // did: the marginal cost of this lookup is a cache hit, never an uncached
+    // fetch+parse. That matters because docs routes are force-dynamic, so this
+    // metadata runs on EVERY page view (every human + crawler). Mirrors the
+    // `useIsr`/`projectDir` derivation in `renderDocPage`'s OpenAPI branch.
+    const specPaths = collectLocalSpecPaths(config.api.openapi);
+    const useIsr = isIsrMode() && !!projectSlug;
+    const projectDir = useIsr ? null : getContentDir();
+    const loadSpecForMeta = async (sp: string): Promise<unknown | null> => {
+      try {
+        if (useIsr && projectSlug) {
+          const { resolveOpenApiSpec } = await import('@/lib/openapi-isr');
+          return await resolveOpenApiSpec(projectSlug, sp);
+        }
+        if (projectDir) {
+          const { api } = await getCachedSpec(sp, projectDir);
+          return api;
+        }
+        return null;
+      } catch {
+        // Any load/parse error degrades to generateAutoDescription below.
+        return null;
+      }
+    };
+    const sourced = await resolveOpenApiMetaDescription(
+      data.openapi, specPaths, loadSpecForMeta,
+    );
+    if (sourced) metaDescription = sourced;
+  }
+
+  return metaDescription || generateAutoDescription(content);
+}
+
 export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
   const { slug: slugInput, projectSlug, hostAtDocs, docsPrefix, requestHeaders } = input;
   const linkPrefix = docsPrefix ?? (hostAtDocs ? '/docs' : '');
@@ -413,59 +486,9 @@ export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
   const parsed = parseFrontmatter(fileContents);
   const data = parsed.data as FrontmatterData;
 
-  // DERIVED for <meta>/OG/Twitter/OG-card only — never written back onto
-  // `data`. `parseFrontmatter` is gray-matter, whose cache returns a shallow
-  // copy that SHARES one `data` object per content string, so an assignment
-  // here reached `renderDocPage`'s own parse of the same page and rendered as
-  // the page SUBTITLE: the operation description twice on every spec-backed
-  // page, and the first paragraph twice on every description-less prose page.
-  // The cache is module-global, so it persisted across requests rather than
-  // being a within-request ordering race. (#7 follow-up.)
-  //
-  // The gate stays on the RAW value, not frontmatterText(): YAML hands back a
-  // Date for `description: 2026-01-01` and a number for `description: 404`.
-  // Both are truthy and must keep suppressing the fallbacks exactly as before.
-  let metaDescription: string | undefined = data.description;
-  if (!metaDescription) {
-    if (typeof data.openapi === 'string' && data.openapi && config.api?.openapi) {
-      // Source the description from the OpenAPI operation before falling back to
-      // first-paragraph extraction (which is empty for prose-less API pages).
-      // The spec loader REUSES the render path's cached loaders — the ISR module
-      // cache (`r2:${slug}:${specPath}`, 10-min TTL) that `renderDocPage`
-      // populates when it renders the page's <ApiEndpoint>, or the static
-      // `getCachedSpec`. So the spec is the same warm parse the render already
-      // did: the marginal cost of this lookup is a cache hit, never an uncached
-      // fetch+parse. That matters because docs routes are force-dynamic, so this
-      // metadata runs on EVERY page view (every human + crawler). Mirrors the
-      // `useIsr`/`projectDir` derivation in `renderDocPage`'s OpenAPI branch.
-      const specPaths = collectLocalSpecPaths(config.api.openapi);
-      const useIsr = isIsrMode() && !!projectSlug;
-      const projectDir = useIsr ? null : getContentDir();
-      const loadSpecForMeta = async (sp: string): Promise<unknown | null> => {
-        try {
-          if (useIsr && projectSlug) {
-            const { resolveOpenApiSpec } = await import('@/lib/openapi-isr');
-            return await resolveOpenApiSpec(projectSlug, sp);
-          }
-          if (projectDir) {
-            const { api } = await getCachedSpec(sp, projectDir);
-            return api;
-          }
-          return null;
-        } catch {
-          // Any load/parse error degrades to generateAutoDescription below.
-          return null;
-        }
-      };
-      const sourced = await resolveOpenApiMetaDescription(
-        data.openapi, specPaths, loadSpecForMeta,
-      );
-      if (sourced) metaDescription = sourced;
-    }
-    if (!metaDescription) {
-      metaDescription = generateAutoDescription(parsed.content);
-    }
-  }
+  const metaDescription = await resolveDerivedDescription(
+    config, data, parsed.content, projectSlug,
+  );
 
   // buildSeoMetadata reads `frontmatter.description` for og:, twitter: and the
   // OG card, so it must see the RESOLVED text — via a copy, never by mutating
@@ -611,7 +634,15 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
 
   const baseUrl = resolveBaseUrl(requestHeaders, projectSlug, hostAtDocs);
   const faqPairs = extractFaqPairs(rawContent);
-  const ogImageUrl = buildPageOgImageUrl(config, data, baseUrl, linkPrefix);
+  // The same resolution buildDocMetadata performs, so og:image and the JSON-LD
+  // `image` point at ONE card. Passed as a copy — never a write onto the shared
+  // `data`, which is what caused #7 in the first place.
+  const ogDescription = await resolveDerivedDescription(
+    config, data, rawContent, projectSlug,
+  );
+  const ogImageUrl = buildPageOgImageUrl(
+    config, { ...data, description: ogDescription }, baseUrl, linkPrefix,
+  );
   // See frontmatterText: a YAML Date title throws when React renders it as a
   // child below, so every consumer in this function reads the coerced value.
   const titleText = frontmatterText(data.title);

package/vendored/lib/seo.ts

@@ -879,7 +879,7 @@ const MAX_DESCRIPTION_LENGTH = 155;
 /** Patterns that indicate a paragraph is not prose (headings, components, images, comments, etc). */
 const NON_PROSE_PATTERNS = [
   /^#{1,6}\s/,       // headings
-  /^<[A-Z]/,         // MDX components
+  /^<\/?[A-Z]/,      // MDX components, opening AND closing (`</ResponseExample>`)
   /^!\[/,            // images
   /^<!--/,           // HTML comments
   /^>/,              // blockquotes