jamdesk 1.1.149 → 1.1.151

package/vendored/lib/build/error-parser.ts

@@ -191,7 +191,9 @@ export function parseErrorDetails(
       '• "name": Your site name\n' +
       '• "theme": One of "jam", "nebula", or "pulsar"\n' +
       '• "colors": { "primary": "#hexcolor" }\n' +
-      '• "navigation": { "anchors": [...] } or { "groups": [...] }\n\n';
+      '• "navigation": one of "tabs", "groups", "pages", "dropdowns", ' +
+      '"versions", "languages", or "products" ' +
+      '(e.g. { "groups": [...] })\n\n';
 
     let suggestion = `${intro}\n\n`;
     if (discoveryHint) {
@@ -249,10 +251,11 @@ export function parseErrorDetails(
         `Error occurred while building: ${file}`,
       suggestion:
         'Check your docs.json configuration file. The "navigation" field ' +
-        'must be an object with "anchors", "tabs", or "groups".\n\n' +
+        'must be an object with one of "tabs", "groups", "pages", ' +
+        '"dropdowns", "versions", "languages", or "products".\n\n' +
         'Example:\n' +
         '"navigation": {\n' +
-        '  "anchors": [{ "anchor": "Docs", "groups": [...] }]\n' +
+        '  "groups": [{ "group": "Docs", "pages": [...] }]\n' +
         '}\n\n' +
         'See https://www.jamdesk.com/docs/navigation for details.',
     };

package/vendored/lib/firestore-helpers.ts

@@ -1,4 +1,4 @@
-import admin from 'firebase-admin';
+import { getFirestore } from 'firebase-admin/firestore';
 
 /**
  * True when a Firestore project claims this slug (the canonical slug lives at
@@ -10,8 +10,7 @@ import admin from 'firebase-admin';
  * dashboard/firestore.indexes.json, so this query needs no new index.
  */
 export async function isSlugActive(slug: string): Promise<boolean> {
-  const snap = await admin
-    .firestore()
+  const snap = await getFirestore()
     .collectionGroup('github')
     .where('slug', '==', slug)
     .limit(1)

package/vendored/lib/fix-engine.ts

@@ -0,0 +1,293 @@
+// builder/build-service/lib/fix-engine.ts
+//
+// Dependency-free deterministic doc-warning fix engine. Imports NOTHING so it
+// byte-syncs into the CLI's src/lib (cli/src cannot import cli/vendored).
+//
+// The engine does NO slugging and NO I/O: the caller injects heading data via
+// FixContext.headingsOf(), populated from the canonical extractHeadings()
+// (heading-extractor.ts) whose ids ARE the real rehype-slug DOM ids. Re-slugging
+// here is forbidden — markdown-only re-slugging diverges from real ids (dedup
+// suffixes shift when <Update>/<Step> anchors share heading text) and was the
+// original wrong-fix bug.
+
+// ---- Types ----------------------------------------------------------------
+
+export interface Edit {
+  file: string;
+  /** 1-indexed source line the edit applies to (from the warning). */
+  line: number;
+  oldText: string;
+  newText: string;
+}
+
+export interface FixResult {
+  status: 'fixed' | 'skipped';
+  edits: Edit[];
+  reason: string;
+}
+
+export interface LocaleInfo {
+  codes: string[];
+  defaultCode: string;
+}
+
+export interface FixWarning {
+  type: string;
+  file: string;
+  line: number | null;
+  link: string;
+  message?: string;
+}
+
+/** Structural subset of heading-extractor's HeadingInfo — extractHeadings()
+ *  output is assignable to EngineHeading[] directly (no mapping). */
+export interface EngineHeading {
+  id: string;
+  stepNumber?: number;
+  isUpdate?: boolean;
+}
+
+export interface FixContext {
+  currentPagePath: string;
+  locales: LocaleInfo;
+  /** Resolve a doc link href to a normalized page path, or null if it does not exist. */
+  resolveLinkPagePath(href: string): string | null;
+  /** Ordered headings for a page path (no extension) via extractHeadings(), or null. */
+  headingsOf(pagePath: string): EngineHeading[] | null;
+}
+
+export type Fixer = (warning: FixWarning, ctx: FixContext) => FixResult;
+
+/** A markdown heading entry (not a <Step> or <Update> component anchor). */
+export function isMarkdownHeading(h: EngineHeading): boolean {
+  return h.stepNumber == null && !h.isUpdate;
+}
+
+/** True iff `candidate` is an exact heading id on `headings`. The canonical
+ *  guard for any externally-sourced (e.g. AI) anchor suggestion — the engine
+ *  itself uses the same `allIds.includes(...)` check inside fixBrokenLink's
+ *  `emit`. Phase 2's AI tier MUST route every suggestion through this so a
+ *  hallucinated fragment can never be written. Pure, dependency-free. */
+export function isRealAnchor(candidate: string, headings: EngineHeading[]): boolean {
+  if (!candidate) return false;
+  return headings.some((h) => h.id === candidate);
+}
+
+/** Substring appended to the skip reason when the deterministic engine defers an
+ *  anchor to the AI tier. Exported so the AI-tier callers match on this constant
+ *  instead of a re-typed literal — producer and consumer cannot drift. */
+export const NEEDS_AI_MARKER = '(needs AI)';
+
+// ---- Edit application -----------------------------------------------------
+
+// A flagged href is always the target of a markdown link `](href)` or an
+// `href="…"`/`href='…'` attribute, so in source it is bounded on the left by a
+// delimiter — never by another URL/path character. A match whose preceding char
+// IS a path character is the href appearing as a SUBSTRING inside a longer URL
+// (e.g. `/setup#x` inside `/guide/setup#x`) and must be skipped, or the edit
+// would corrupt an unrelated, valid link on the same line.
+const URL_PATH_CHAR = /[A-Za-z0-9\-._~%/#?:@]/;
+
+/** Index of the next occurrence of `href` at/after `from` that sits at a link
+ *  boundary (not as a substring inside a longer path), or -1. */
+function findHrefBoundary(line: string, href: string, from: number): number {
+  let pos = line.indexOf(href, from);
+  while (pos !== -1) {
+    if (pos === 0 || !URL_PATH_CHAR.test(line[pos - 1])) return pos;
+    pos = line.indexOf(href, pos + 1);
+  }
+  return -1;
+}
+
+/**
+ * Apply edits, replacing each edit's oldText with newText on its specific
+ * (1-indexed) source line. Line-scoped, so an identical href on another line
+ * (e.g. a code sample) is never touched. Within a line: oldText is matched at a
+ * link boundary (so a short href is never replaced inside a longer one),
+ * matching runs against the ORIGINAL line (so an edit whose newText contains its
+ * oldText is never re-matched), and edits apply right-to-left so earlier
+ * positions keep their indices. Identical oldTexts on one line consume
+ * successive occurrences. Throws if a line is out of range or an oldText is
+ * absent — a missing match means the source changed since the fix was derived,
+ * and a partial/wrong edit must never be written.
+ */
+export function applyEdits(content: string, edits: Edit[]): string {
+  if (edits.length === 0) return content;
+  const lines = content.split('\n');
+
+  const byLine = new Map<number, Edit[]>();
+  for (const edit of edits) {
+    const list = byLine.get(edit.line);
+    if (list) list.push(edit);
+    else byLine.set(edit.line, [edit]);
+  }
+
+  for (const [line, lineEdits] of byLine) {
+    const idx = line - 1;
+    if (idx < 0 || idx >= lines.length) {
+      throw new Error(`applyEdits: line ${line} out of range (${lines.length} lines)`);
+    }
+    const src = lines[idx];
+    // Resolve every edit to a concrete [start,end) span on the ORIGINAL line.
+    const spans: Array<{ start: number; end: number; newText: string }> = [];
+    const nextFrom = new Map<string, number>();
+    for (const edit of lineEdits) {
+      const from = nextFrom.get(edit.oldText) ?? 0;
+      const start = findHrefBoundary(src, edit.oldText, from);
+      if (start === -1) {
+        throw new Error(`applyEdits: oldText not found on line ${line}: ${JSON.stringify(edit.oldText)}`);
+      }
+      const end = start + edit.oldText.length;
+      nextFrom.set(edit.oldText, end);
+      spans.push({ start, end, newText: edit.newText });
+    }
+    // Apply right-to-left so an earlier span's indices survive later edits.
+    spans.sort((a, b) => b.start - a.start);
+    let out = src;
+    for (const s of spans) out = out.slice(0, s.start) + s.newText + out.slice(s.end);
+    lines[idx] = out;
+  }
+  return lines.join('\n');
+}
+
+// ---- Distance / nearest-slug (ported from validate-links.cjs) -------------
+
+const MAX_SUGGESTION_DISTANCE = 2;
+
+export function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array<number>(b.length + 1);
+  let curr = new Array<number>(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 0; i < a.length; i++) {
+    curr[0] = i + 1;
+    for (let j = 0; j < b.length; j++) {
+      const cost = a[i] === b[j] ? 0 : 1;
+      curr[j + 1] = Math.min(curr[j] + 1, prev[j + 1] + 1, prev[j] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+export function closestSlug(fragment: string, slugs: Iterable<string>): string | null {
+  if (!fragment) return null;
+  let best: string | null = null;
+  let bestDist = Infinity;
+  let secondDist = Infinity;
+  for (const slug of slugs) {
+    if (Math.abs(fragment.length - slug.length) > MAX_SUGGESTION_DISTANCE) continue;
+    const d = levenshtein(fragment, slug);
+    if (d < bestDist) {
+      secondDist = bestDist;
+      bestDist = d;
+      best = slug;
+    } else if (d < secondDist) {
+      secondDist = d;
+    }
+  }
+  return best !== null && bestDist >= 1 && bestDist <= MAX_SUGGESTION_DISTANCE && bestDist < secondDist
+    ? best
+    : null;
+}
+
+// ---- Link + locale helpers ------------------------------------------------
+
+export function parseHref(href: string): { path: string | null; fragment: string | null } {
+  const i = href.indexOf('#');
+  if (i === -1) return { path: href, fragment: null };
+  return { path: i === 0 ? null : href.slice(0, i), fragment: href.slice(i + 1) || null };
+}
+
+export function normalizeLinkPath(linkPath: string, hostAtDocs: boolean): string {
+  let p = linkPath;
+  if (hostAtDocs && p.startsWith('/docs/')) p = p.slice('/docs/'.length);
+  if (p.startsWith('/')) p = p.slice(1);
+  return p.replace(/\.mdx$/, '');
+}
+
+/** The default-locale twin of a localized page path, or null if already default. */
+export function defaultTwinPath(pagePath: string, locales: LocaleInfo): string | null {
+  const segments = pagePath.split('/');
+  const first = segments[0];
+  if (first !== locales.defaultCode && locales.codes.includes(first)) {
+    return segments.slice(1).join('/');
+  }
+  return null;
+}
+
+// ---- Broken-link fixer ----------------------------------------------------
+
+function skip(reason: string): FixResult {
+  return { status: 'skipped', edits: [], reason };
+}
+
+export const fixBrokenLink: Fixer = (warning, ctx) => {
+  const { path: linkPath, fragment } = parseHref(warning.link);
+  if (!fragment) return skip('not a fragment link — out of scope for phase 1');
+  if (!linkPath) return skip('same-page fragment — out of scope for phase 1');
+  if (warning.line == null) return skip('warning has no line — cannot place a safe edit');
+
+  const targetPage = ctx.resolveLinkPagePath(linkPath);
+  if (!targetPage) return skip('target page could not be resolved');
+  const targetHeadings = ctx.headingsOf(targetPage);
+  if (!targetHeadings) return skip('target page headings could not be read');
+
+  const allIds = targetHeadings.map((h) => h.id);
+
+  // (0) Re-derivation: may already be valid in current source.
+  if (allIds.includes(fragment)) return skip('already valid — fragment exists on target');
+
+  // Emit only a fragment that is a REAL anchor on the target (never point at a
+  // non-existent or wrong-kind id), reconstructing the href (no substring replace).
+  const emit = (candidate: string, reason: string): FixResult => {
+    if (!allIds.includes(candidate)) return skip('internal: candidate is not a real anchor — refusing');
+    return {
+      status: 'fixed',
+      edits: [{ file: warning.file, line: warning.line as number, oldText: warning.link, newText: linkPath + '#' + candidate }],
+      reason,
+    };
+  };
+
+  // (1) Cross-locale positional map FIRST (high precision for localized targets).
+  // Ordinals over MARKDOWN headings only (so <Step>/<Update> can't misalign them),
+  // but the emitted id is the target heading's REAL id (full-set dedup).
+  const twinPage = defaultTwinPath(targetPage, ctx.locales);
+  if (twinPage) {
+    const twinHeadings = ctx.headingsOf(twinPage);
+    if (twinHeadings) {
+      const twinMd = twinHeadings.filter(isMarkdownHeading);
+      const targetMd = targetHeadings.filter(isMarkdownHeading);
+      const ordinal = twinMd.findIndex((h) => h.id === fragment);
+      if (ordinal !== -1 && twinMd.length === targetMd.length && targetMd[ordinal]) {
+        return emit(targetMd[ordinal].id, `cross-locale positional map: #${fragment} → #${targetMd[ordinal].id}`);
+      }
+    }
+  }
+
+  // (2) Near-miss fallback (typos within the same language).
+  const near = closestSlug(fragment, allIds);
+  if (near) return emit(near, `near-miss: #${fragment} → #${near}`);
+
+  return skip(`no confident deterministic fix — structures diverge or target is ambiguous ${NEEDS_AI_MARKER}`);
+};
+
+// ---- Registry + engine entry point ----------------------------------------
+
+/** Fixer registry keyed by BuildWarningType. Phase 1: broken_link only. */
+export const FIXERS: Record<string, Fixer> = {
+  broken_link: fixBrokenLink,
+};
+
+/**
+ * Run the registered fixer for a warning. Deterministic-first is implemented
+ * inside each fixer (exact strategies, then 'skipped' for AI cases). The AI
+ * fallback tier is wired in Phase 2; until then a 'skipped' result is terminal.
+ */
+export function runFixer(warning: FixWarning, ctx: FixContext): FixResult {
+  const fixer = FIXERS[warning.type];
+  if (!fixer) return skip(`no fixer registered for type "${warning.type}"`);
+  return fixer(warning, ctx);
+}

package/vendored/lib/health-checks.ts

@@ -190,10 +190,10 @@ export async function checkFirestoreHealth(db: Firestore): Promise<FirestoreHeal
     let writeLatencyMs: number | null = null;
     try {
       const writeStart = Date.now();
-      const admin = await import('firebase-admin');
+      const { FieldValue } = await import('firebase-admin/firestore');
       await Promise.race([
         healthRef.set(
-          { lastCheck: admin.firestore.FieldValue.serverTimestamp() },
+          { lastCheck: FieldValue.serverTimestamp() },
           { merge: true }
         ),
         new Promise((_, reject) =>

package/vendored/lib/json-ld.ts

@@ -1,15 +1,17 @@
 /**
  * JSON-LD Structured Data for Documentation Pages
  *
- * Generates WebSite + BreadcrumbList schemas for search engine rich results.
+ * Generates WebSite + Organization + BreadcrumbList schemas for search engine rich results.
  * Rendered as <script type="application/ld+json"> in page.tsx.
  *
  * Breadcrumb path extraction is server-side only (pure functions, no hooks).
  * Intentionally separate from Breadcrumb.tsx which is a 'use client' component.
  */
 
-import type { DocsConfig, NavigationPage, GroupConfig } from './docs-types';
-import { normalizeNavPage } from './docs-types';
+import type { DocsConfig, NavigationPage, GroupConfig, LanguageCode } from './docs-types';
+import { normalizeNavPage, normalizeLogo } from './docs-types';
+import { normalizeLanguageList, deriveChunkLocale } from './locale-helpers';
+import { getUiStrings } from './ui-strings';
 import type { FaqPair } from './extract-faq';
 
 interface BreadcrumbEntry {
@@ -23,6 +25,10 @@ export interface JsonLdOptions {
   pageTitle: string;
   baseUrl: string;
   faqPairs?: FaqPair[];
+  isRootAlias?: boolean;
+  ogImageUrl?: string;
+  dateModified?: string;
+  author?: string;
 }
 
 export interface JsonLdGraph {
@@ -69,7 +75,14 @@ export function findBreadcrumbPath(
   config: DocsConfig, targetSlug: string, baseUrl: string, pageTitle?: string
 ): BreadcrumbEntry[] {
   const nav = config.navigation;
-  const home: BreadcrumbEntry = { name: 'Home', url: baseUrl };
+  // Localize the root crumb label so a Spanish/French page's breadcrumb rich
+  // result reads "Inicio"/"Accueil", not "Home". deriveChunkLocale only treats
+  // the leading slug segment as a locale when it's a configured language (and
+  // falls back to the tenant's default language), so single-language sites are
+  // unaffected. The visual breadcrumb uses a house icon, so this is JSON-LD only.
+  const locale = deriveChunkLocale(targetSlug, normalizeLanguageList(nav?.languages));
+  const homeLabel = getUiStrings((locale ?? undefined) as LanguageCode | undefined).breadcrumbHome;
+  const home: BreadcrumbEntry = { name: homeLabel, url: baseUrl };
   const pageEntry: BreadcrumbEntry = {
     name: pageTitle || formatSlugAsTitle(targetSlug),
     url: `${baseUrl}/${targetSlug}`,
@@ -142,25 +155,102 @@ export function findBreadcrumbPath(
   );
 }
 
+// sameAs is for identity/disambiguation PROFILES, not the company homepage.
+// `website` and `earth-americas` are both homepage-link social keys — excluded
+// (along with any empty values) so the entity isn't muddied with a non-profile URL.
+const NON_PROFILE_SOCIALS = new Set(['website', 'earth-americas']);
+
+/** Absolute brand-logo URL for the Organization node, or undefined if no logo. */
+function resolveLogoUrl(config: DocsConfig, baseUrl: string): string | undefined {
+  const norm = normalizeLogo(config.logo);
+  const path = norm?.light || norm?.dark;
+  if (!path) return undefined;
+  if (path.startsWith('http')) return path;
+  const rootUrl = baseUrl.replace(/\/docs$/, '');
+  return `${rootUrl}${path.startsWith('/') ? '' : '/'}${path}`;
+}
+
 /**
  * Build JSON-LD structured data for a documentation page.
- * Returns a schema.org @graph with WebSite + BreadcrumbList.
+ * Returns a schema.org @graph with WebSite + Organization + BreadcrumbList (+ optional FAQPage).
  */
 export function buildJsonLd(options: JsonLdOptions): JsonLdGraph {
-  const { config, pagePath, pageTitle, baseUrl, faqPairs } = options;
+  const {
+    config, pagePath, pageTitle, baseUrl, faqPairs,
+    isRootAlias = false, ogImageUrl, dateModified, author: pageAuthor,
+  } = options;
   const breadcrumbs = findBreadcrumbPath(config, pagePath, baseUrl, pageTitle);
+  const pageUrl = breadcrumbs.length ? breadcrumbs[breadcrumbs.length - 1].url : baseUrl;
+
+  const websiteId = `${baseUrl}#website`;
+  const orgId = `${baseUrl}#organization`;
+  const breadcrumbId = `${pageUrl}#breadcrumb`;
+  const faqId = `${pageUrl}#faq`;
+
+  const logoUrl = resolveLogoUrl(config, baseUrl);
+  const socials = config.footer?.socials
+    ? Object.entries(config.footer.socials)
+        .filter(([key, url]) => Boolean(url) && !NON_PROFILE_SOCIALS.has(key))
+        .map(([, url]) => url as string)
+    : [];
+
+  const organization: Record<string, unknown> = {
+    '@type': 'Organization',
+    '@id': orgId,
+    name: config.name,
+    url: baseUrl,
+    ...(logoUrl && { logo: { '@type': 'ImageObject', url: logoUrl } }),
+    ...(socials.length && { sameAs: socials }),
+  };
+
+  const mainId = `${pageUrl}#${isRootAlias ? 'webpage' : 'article'}`;
+  const author = pageAuthor
+    ? { '@type': 'Person', name: pageAuthor }
+    : { '@id': orgId };
+
+  const mainNode: Record<string, unknown> = isRootAlias
+    ? {
+        '@type': 'WebPage',
+        '@id': mainId,
+        name: pageTitle,
+        url: pageUrl,
+        isPartOf: { '@id': websiteId },
+        // `breadcrumb` is a WebPage-only schema.org property, so it belongs here but
+        // NOT on the TechArticle branch below — the standalone BreadcrumbList node
+        // carries the trail for article pages (putting it on an Article fails validation).
+        breadcrumb: { '@id': breadcrumbId },
+        ...(ogImageUrl && { image: ogImageUrl }),
+        ...(dateModified && { dateModified }),
+      }
+    : {
+        '@type': 'TechArticle',
+        '@id': mainId,
+        headline: pageTitle,
+        url: pageUrl,
+        isPartOf: { '@id': websiteId },
+        mainEntityOfPage: pageUrl,
+        author,
+        publisher: { '@id': orgId },
+        ...(ogImageUrl && { image: ogImageUrl }),
+        ...(dateModified && { dateModified }),
+      };
 
   return {
     '@context': 'https://schema.org',
     '@graph': [
       {
         '@type': 'WebSite',
+        '@id': websiteId,
         name: config.name,
         url: baseUrl,
         ...(config.description && { description: config.description }),
+        publisher: { '@id': orgId },
       },
+      organization,
+      mainNode,
       {
         '@type': 'BreadcrumbList',
+        '@id': breadcrumbId,
         itemListElement: breadcrumbs.map((item, i) => ({
           '@type': 'ListItem',
           position: i + 1,
@@ -171,6 +261,8 @@ export function buildJsonLd(options: JsonLdOptions): JsonLdGraph {
       ...(faqPairs && faqPairs.length
         ? [{
             '@type': 'FAQPage',
+            '@id': faqId,
+            isPartOf: { '@id': websiteId },
             mainEntity: faqPairs.map((p) => ({
               '@type': 'Question', name: p.question,
               acceptedAnswer: { '@type': 'Answer', text: p.answer },

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

@@ -61,7 +61,7 @@ import { buildEndpointFromMdx } from '@/lib/build-endpoint-from-mdx';
 import { mdxSecurityOptions } from '@/lib/mdx-security-options';
 import { getContentDir } from '@/lib/docs';
 import type { DocsConfig } from '@/lib/docs-types';
-import { buildSeoMetadata, generateAutoDescription, buildSiteTitle } from '@/lib/seo';
+import { buildSeoMetadata, generateAutoDescription, buildSiteTitle, buildPageOgImageUrl } from '@/lib/seo';
 import { buildJsonLd } from '@/lib/json-ld';
 import { extractFaqPairs } from '@/lib/extract-faq';
 import {
@@ -318,7 +318,8 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
   const highlighterP = getHighlighter();
 
   const normalizedSlug = normalizeSlugForContent(slugInput || [], hostAtDocs);
-  const slug = needsSlugRewrite(normalizedSlug)
+  const isRootAlias = needsSlugRewrite(normalizedSlug);
+  const slug = isRootAlias
     ? resolveSlug(normalizedSlug, await configP)
     : normalizedSlug;
   const pagePath = slug.join('/');
@@ -339,12 +340,17 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
 
   const baseUrl = resolveBaseUrl(requestHeaders, projectSlug, hostAtDocs);
   const faqPairs = extractFaqPairs(rawContent);
+  const ogImageUrl = buildPageOgImageUrl(config, data, baseUrl);
   const jsonLd = buildJsonLd({
     config,
     pagePath,
     pageTitle: data.title || pagePath,
     baseUrl,
     faqPairs,
+    isRootAlias,
+    ogImageUrl,
+    dateModified: typeof data.lastUpdated === 'string' ? data.lastUpdated : undefined,
+    author: typeof data.author === 'string' ? data.author : undefined,
   });
   const jsonLdScript = renderJsonLdScript(jsonLd);
 

package/vendored/lib/search.ts

@@ -23,8 +23,8 @@ let searchDocuments: SearchResult[] = [];
 
 function stripMarkdown(text: string): string {
   return text
-    .replace(/```[\s\S]*?```/g, '') // Remove code blocks
-    .replace(/`[^`]+`/g, '') // Remove inline code
+    .replace(/```[\s\S]*?```/g, '') // Remove code blocks (too noisy to index)
+    .replace(/`([^`]+)`/g, '$1') // Inline code → keep text, drop backticks (config keys like starterQuestions stay searchable)
     .replace(/#{1,6}\s/g, '') // Remove heading markers
     .replace(/\*\*([^*]+)\*\*/g, '$1') // Remove bold
     .replace(/\*([^*]+)\*/g, '$1') // Remove italic

package/vendored/lib/seo.ts

@@ -132,6 +132,34 @@ function buildOgImageUrl(
   return `${rootUrl}${ogPath}?${params.toString()}`;
 }
 
+/**
+ * Public OG-card URL builder. Mirrors the global+page metatag merge that
+ * buildSeoMetadata performs, so callers outside the metadata path (the JSON-LD
+ * layer) can set an article image to the exact same card the og:image points at.
+ */
+export function buildPageOgImageUrl(
+  config: DocsConfig,
+  frontmatter: PageFrontmatter,
+  baseUrl: string,
+): string {
+  const globalMeta = config.seo?.metatags || {};
+  const pageMeta = normalizePageMetatags(frontmatter as Record<string, unknown>);
+  const metatags: Record<string, string> = { ...globalMeta, ...pageMeta };
+  const customImage = metatags['og:image']?.trim();
+  return buildOgImageUrl(
+    baseUrl,
+    metatags['og:title'] || frontmatter.title || 'Documentation',
+    config.name,
+    {
+      description: metatags['og:description'] || frontmatter.description,
+      section: frontmatter.section,
+      logo: config.logo,
+      favicon: config.favicon,
+      bg: customImage || undefined,
+    },
+  );
+}
+
 /**
  * Coerce a raw frontmatter value into a meta-tag string.
  * Mintlify allows numbers (`og:image:width: 1200`) and arrays
@@ -737,19 +765,7 @@ export function buildSeoMetadata(
     // than a bare static image, so the emitted OG image is always the generated card.
     // The card text follows og:title/og:description overrides so the image matches
     // the link-card text built in buildOpenGraphMetadata.
-    const customImage = metatags['og:image']?.trim();
-    const ogImageUrl = buildOgImageUrl(
-      baseUrl,
-      metatags['og:title'] || frontmatter.title || 'Documentation',
-      config.name,
-      {
-        description: metatags['og:description'] || frontmatter.description,
-        section: frontmatter.section,
-        logo: config.logo,
-        favicon: config.favicon,
-        bg: customImage || undefined,
-      },
-    );
+    const ogImageUrl = buildPageOgImageUrl(config, frontmatter, baseUrl);
     metadata.openGraph = buildOpenGraphMetadata(metatags, {
       title: frontmatter.title,
       description: frontmatter.description,

package/vendored/lib/static-artifacts.ts

@@ -1003,8 +1003,8 @@ function inferPageType(slug: string): string {
  */
 export function stripMarkdown(text: string): string {
   return text
-    .replace(/```[\s\S]*?```/g, '')    // code blocks
-    .replace(/`[^`]+`/g, '')           // inline code
+    .replace(/```[\s\S]*?```/g, '')    // code blocks (dropped — too noisy to index)
+    .replace(/`([^`]+)`/g, '$1')       // inline code → keep text, drop backticks (config keys like starterQuestions stay searchable)
     .replace(/#{1,6}\s/g, '')          // headings
     .replace(/\*\*([^*]+)\*\*/g, '$1') // bold
     .replace(/\*([^*]+)\*/g, '$1')     // italic

package/vendored/lib/ui-strings.ts

@@ -6,6 +6,8 @@ export interface UiStrings {
   more: string;
   toggleMenu: string;
   selectLanguage: string;
+  /** Root crumb label in the JSON-LD BreadcrumbList (Google rich result). */
+  breadcrumbHome: string;
 }
 
 const EN: UiStrings = {
@@ -14,6 +16,7 @@ const EN: UiStrings = {
   more: 'More',
   toggleMenu: 'Toggle menu',
   selectLanguage: 'Select language',
+  breadcrumbHome: 'Home',
 };
 
 const ZH: Partial<UiStrings> = {
@@ -22,6 +25,7 @@ const ZH: Partial<UiStrings> = {
   more: '更多',
   toggleMenu: '切换菜单',
   selectLanguage: '选择语言',
+  breadcrumbHome: '首页',
 };
 
 const OVERRIDES: Partial<Record<LanguageCode, Partial<UiStrings>>> = {
@@ -31,6 +35,7 @@ const OVERRIDES: Partial<Record<LanguageCode, Partial<UiStrings>>> = {
     more: 'Plus',
     toggleMenu: 'Basculer le menu',
     selectLanguage: 'Choisir la langue',
+    breadcrumbHome: 'Accueil',
   },
   es: {
     search: 'Buscar',
@@ -38,6 +43,7 @@ const OVERRIDES: Partial<Record<LanguageCode, Partial<UiStrings>>> = {
     more: 'Más',
     toggleMenu: 'Alternar menú',
     selectLanguage: 'Elegir idioma',
+    breadcrumbHome: 'Inicio',
   },
   zh: ZH,
   cn: ZH,