jamdesk 1.1.148 → 1.1.150

package/vendored/lib/json-ld.ts

@@ -1,15 +1,18 @@
 /**
  * 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 {
   name: string;
@@ -21,6 +24,11 @@ export interface JsonLdOptions {
   pagePath: string;
   pageTitle: string;
   baseUrl: string;
+  faqPairs?: FaqPair[];
+  isRootAlias?: boolean;
+  ogImageUrl?: string;
+  dateModified?: string;
+  author?: string;
 }
 
 export interface JsonLdGraph {
@@ -67,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}`,
@@ -106,7 +121,7 @@ export function findBreadcrumbPath(
   // Search all navigation structures (mirrors Breadcrumb.tsx order)
   let trail: BreadcrumbEntry[] | null = null;
 
-  if (!trail && nav.languages) {
+  if (nav && !trail && nav.languages) {
     for (const lang of nav.languages) {
       if (!lang.tabs) continue;
       for (const tab of lang.tabs) {
@@ -116,19 +131,19 @@ export function findBreadcrumbPath(
       if (trail) break;
     }
   }
-  if (!trail && nav.anchors) {
+  if (nav && !trail && nav.anchors) {
     for (const anchor of nav.anchors) {
       if (anchor.groups) trail = searchGroups(anchor.groups);
       if (trail) break;
     }
   }
-  if (!trail && nav.tabs) {
+  if (nav && !trail && nav.tabs) {
     for (const tab of nav.tabs) {
       if (tab.groups) trail = searchGroups(tab.groups);
       if (trail) break;
     }
   }
-  if (!trail && nav.groups) {
+  if (nav && !trail && nav.groups) {
     trail = searchGroups(nav.groups);
   }
 
@@ -140,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 } = 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,
@@ -166,6 +258,17 @@ export function buildJsonLd(options: JsonLdOptions): JsonLdGraph {
           item: item.url,
         })),
       },
+      ...(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/layout-helpers.tsx

@@ -3,7 +3,7 @@
 // or — in non-ISR dev/tests — from URL params; this module owns the
 // rendering once those have resolved.
 import { Inter, JetBrains_Mono } from 'next/font/google';
-import { preload, preinit } from 'react-dom';
+import { preinit } from 'react-dom';
 import fs from 'fs';
 import path from 'path';
 import { ThemeProvider } from '@/components/theme/ThemeProvider';
@@ -454,22 +454,21 @@ export async function DocsChrome({
   const bannerNoFlash = !embed && !!bannerContent && config.banner?.dismissible === true && !!resolvedProjectSlug;
 
   // Font Awesome CSS uses preinit (not preload) so React 19 emits the
-  // stylesheet link in <head> at SSR time. The previous approach used a
-  // beforeInteractive Script that injected <link rel=stylesheet> at runtime —
-  // that delayed @font-face parsing past the preloaded fonts' "few seconds"
-  // grace window, producing the chrome console warning "preloaded but not
-  // used within a few seconds." preinit closes the gap: the preloaded fonts
-  // are matched to their @font-face declarations as soon as the stylesheet
-  // parses, which now starts at HTML-parse time alongside the preloads.
+  // stylesheet link in <head> at SSR time. preinit (rather than a runtime
+  // beforeInteractive <Script>/<link> injection) is what gets the @font-face
+  // rules parsed early: the previous Script that ran document.createElement at
+  // parse time delayed @font-face parsing, so the actual woff2 fetch started
+  // late. preinit hoists the stylesheet at HTML-parse time instead.
   //
-  // The font preloads stay on react-dom preload() so React 19 dedupes them
-  // (JSX <link rel=preload> tags used to ship twice — once from the JSX tree,
-  // once from React's preload manager). The <noscript> fallback below uses
-  // dangerouslySetInnerHTML for the same reason: a JSX <link rel=stylesheet>
-  // inside noscript was being hoisted into <head> as a real stylesheet.
+  // The individual woff2 weights are deliberately NOT preloaded — they load on
+  // demand when the stylesheet's @font-face rules are matched to the icons a
+  // page actually uses. The default docs icon weight is solid, so the previous
+  // unconditional fa-light-300 / fa-brands-400 preloads were almost never used
+  // and Chrome flagged them "preloaded but not used within a few seconds."
+  // The <noscript> fallback below uses dangerouslySetInnerHTML because a JSX
+  // <link rel=stylesheet> inside noscript was being hoisted into <head> as a
+  // real stylesheet by React 19.
   preinit(FA_CSS_HREF, { as: 'style' });
-  preload('/_jd/fonts/fontawesome/webfonts/fa-light-300.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' });
-  preload('/_jd/fonts/fontawesome/webfonts/fa-brands-400.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' });
 
   return (
     <html lang={toHreflang(lang)} dir={dir} suppressHydrationWarning data-scroll-behavior="smooth" data-scroll-locked="true">

package/vendored/lib/llms-flag.ts

@@ -0,0 +1,5 @@
+import type { DocsConfig } from './docs-types';
+
+export function isLlmsTxtEnabled(config: DocsConfig): boolean {
+  return config.seo?.ai?.llmsTxt !== false;
+}

package/vendored/lib/logo-warning.ts

@@ -0,0 +1,35 @@
+import type { BuildWarning } from '../shared/status-reporter.js'; // vendored copy — NOT '../../shared'
+import type { Logo } from './docs-types.js';
+
+const MAX_LOGO_BYTES = 100 * 1024;
+const MAX_REASONABLE_WIDTH = 720; // 2x the LOGO_MAX_WIDTH target
+
+/**
+ * Collect the distinct image refs from a logo config (string or {light,dark}),
+ * in light-then-dark order with empties dropped.
+ *
+ * Used to SNAPSHOT the originals before the convertToWebp pass can rewrite them:
+ * an object {light,dark} logo shares its nested object across the enhancedConfig
+ * shallow spread, so a later in-place ".webp" rewrite mutates docsConfig.logo too —
+ * destroying the ".png"/".jpg" refs the always-on downscale needs. Reading from a
+ * pre-convert snapshot makes the downscale work for object logos, not just strings.
+ */
+export function collectLogoRefs(logo: Logo | undefined): string[] {
+  const refs: string[] = [];
+  if (typeof logo === 'string') {
+    refs.push(logo);
+  } else if (logo && typeof logo === 'object') {
+    if (logo.light) refs.push(logo.light);
+    if (logo.dark) refs.push(logo.dark);
+  }
+  return [...new Set(refs.filter(Boolean))];
+}
+
+export function buildLogoWarning(logo: { path: string; width: number; height: number; bytes: number }): BuildWarning | null {
+  if (logo.bytes <= MAX_LOGO_BYTES && logo.width <= MAX_REASONABLE_WIDTH) return null;
+  return {
+    type: 'logo_oversized',
+    file: logo.path,
+    message: `Logo is ${logo.width}×${logo.height} (${Math.round(logo.bytes / 1024)} KB). It's auto-downscaled, but uploading a logo ≤ ${MAX_REASONABLE_WIDTH}px wide / ≤ 100 KB avoids shipping a large source.`,
+  };
+}

package/vendored/lib/noindex-warning.ts

@@ -0,0 +1,14 @@
+// NOTE: lib/*.ts import the VENDORED shared copy at build-service/shared via
+// '../shared/...js' (see other lib files). '../../shared' would resolve outside the
+// build-service package and break tsc + the prod build.
+import type { BuildWarning } from '../shared/status-reporter.js';
+
+export function buildNoindexWarning(noindex: boolean): BuildWarning | null {
+  if (!noindex) return null;
+  return {
+    type: 'site_noindex',
+    file: 'docs.json',
+    message:
+      'This site is set to noindex: robots.txt is "Disallow: /" and the sitemap is empty, so it will not be indexed by any search engines. AI crawlers are still served via llms.txt (set seo.ai.llmsTxt: false to disable). Remove "noindex" from seo.metatags.robots to allow search indexing.',
+  };
+}

package/vendored/lib/r2-cleanup.ts

@@ -442,6 +442,32 @@ export async function sweepStaleLocaleLlmsTxt(
   return staleKeys;
 }
 
+/**
+ * Delete a project's AI-context files: the root `llms.txt` + `llms-full.txt` and
+ * every per-locale `<locale>/llms.txt`. Called on every build where `seo.ai.llmsTxt`
+ * is false so a previously published llms.txt stops serving after a customer opts
+ * out — the build gate stops REGENERATING these files but otherwise leaves the
+ * already-uploaded copies in place. The deletes are idempotent (DeleteObject is a
+ * no-op-success on a missing key), so re-running on later disabled-llms builds is
+ * harmless and self-healing. Per-locale files are discovered and deleted by
+ * sweepStaleLocaleLlmsTxt with an EMPTY active-locale set (every known-language
+ * locale then counts as removable). Note the returned array lists the keys
+ * TARGETED, not necessarily ones that existed. Non-fatal by contract: callers treat
+ * a throw as a warning — a stale llms.txt is a cosmetic orphan, never build-failing.
+ */
+export async function deleteLlmsTxtArtifacts(projectSlug: string): Promise<string[]> {
+  const localeKeys = await sweepStaleLocaleLlmsTxt(projectSlug, new Set());
+  const client = getR2S3Client();
+  const { bucketName } = getR2Config();
+  const rootKeys = [`${projectSlug}/llms.txt`, `${projectSlug}/llms-full.txt`];
+  // Independent keys — delete concurrently (matches deleteRemovedR2Objects' Promise.all).
+  // A rejection propagates so the caller's non-fatal try/catch logs it; see doc above.
+  await Promise.all(
+    rootKeys.map((key) => client.send(new DeleteObjectCommand({ Bucket: bucketName, Key: key }))),
+  );
+  return [...localeKeys, ...rootKeys];
+}
+
 /**
  * Delete EVERY R2 object under the `{slug}/` prefix.
  *

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

@@ -61,8 +61,9 @@ 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 {
   getContentLoader,
   isIsrMode,
@@ -317,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('/');
@@ -337,11 +339,18 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
   const rawContent = parsed.content;
 
   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
@@ -615,6 +643,18 @@ function derivePageLocale(pagePath: string, languages?: LanguageConfig[]): strin
  *   the full hreflang cluster, so language discovery is preserved.
  * @returns Partial<Metadata> to spread into generateMetadata return
  */
+
+// Next.js Metadata.robots can be a string OR an object. When we must ALSO emit
+// googlebot (object-only), a raw string robots directive would be lost — convert
+// it to object form first so the general directive survives the merge.
+function parseRobotsString(robots: string): { index: boolean; follow: boolean } {
+  const tokens = robots.toLowerCase().split(',').map((t) => t.trim());
+  return {
+    index: !tokens.includes('noindex'),
+    follow: !tokens.includes('nofollow'),
+  };
+}
+
 export function buildSeoMetadata(
   config: DocsConfig,
   frontmatter: PageFrontmatter,
@@ -653,12 +693,14 @@ export function buildSeoMetadata(
 
   // 3. Googlebot (separate from robots)
   if (metatags.googlebot) {
-    // Merge googlebot with existing robots config
-    const existingRobots = typeof metadata.robots === 'object' ? metadata.robots : {};
-    metadata.robots = {
-      ...existingRobots,
-      googleBot: metatags.googlebot,
-    };
+    // Merge googlebot with existing robots config. When metadata.robots is a string
+    // (set above from metatags.robots), coerce it to object form first so the general
+    // directive (e.g. noindex) is not silently dropped by the spread.
+    const base =
+      typeof metadata.robots === 'string'
+        ? parseRobotsString(metadata.robots)
+        : (metadata.robots ?? {});
+    metadata.robots = { ...base, googleBot: metatags.googlebot };
   }
 
   // 4. Google site verification
@@ -723,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,

package/vendored/lib/validate-config.ts

@@ -257,10 +257,65 @@ function deduplicateErrors(errors: ErrorObject[]): ErrorObject[] {
   });
 }
 
+const NAV_BRANCH_KEYS = [
+  'products', 'languages', 'versions', 'tabs',
+  'dropdowns', 'groups', 'pages',
+] as const;
+
+/**
+ * Collapse the navigation anyOf noise. When the user's navigation clearly uses
+ * one discriminator key (e.g. `tabs`), drop the sibling-branch
+ * `required`/`additionalProperties` errors AT `/navigation` and keep the deeper
+ * child errors (e.g. /navigation/tabs/0) that say what's actually wrong. No-op
+ * when navigation is absent or the intent is ambiguous (0 or >1 known keys).
+ *
+ * IMPORTANT: key the predicate on `instancePath` + `keyword` + `params`, NOT
+ * `schemaPath`. Ajv resolves the `$ref: "#/definitions/navigationSchema"`, so
+ * the nav-branch errors carry schemaPaths like `#/anyOf/0/required` — the
+ * string "navigationSchema" never appears in them. (Verified by compiling the
+ * real schema against a malformed-tabs config.) `instancePath` is the stable
+ * signal: every sibling-branch red herring sits exactly at `/navigation`,
+ * while the actionable child error sits at `/navigation/<key>/...`.
+ * Runs BEFORE `filterAnyOfNoise`, so schemaPaths are still `#/anyOf/N/...` here.
+ */
+export function filterNavigationAnyOfNoise(
+  errors: ErrorObject[],
+  navigation: Record<string, unknown> | undefined,
+): ErrorObject[] {
+  if (!navigation) return errors;
+  const present = NAV_BRANCH_KEYS.filter((k) => k in navigation);
+  // Only collapse noise when the user's intent is unambiguous — exactly one
+  // discriminator key. Zero keys or multiple keys (itself invalid) → leave
+  // the raw errors so we never hide the real problem.
+  if (present.length !== 1) return errors;
+  const usedKey = present[0];
+
+  return errors.filter((err) => {
+    // Keep everything except the two red-herring classes AT /navigation.
+    // Child errors like /navigation/tabs/0 have a deeper instancePath -> kept.
+    if (err.instancePath !== '/navigation') return true;
+    // Drop sibling-branch "missing required <otherKey>" noise (e.g. products).
+    if (err.keyword === 'required') {
+      const missing =
+        (err.params as { missingProperty?: string }).missingProperty;
+      return !(missing && missing !== usedKey &&
+        (NAV_BRANCH_KEYS as readonly string[]).includes(missing));
+    }
+    // Drop "unknown property <usedKey>" flagged by non-matching sibling
+    // branches (e.g. additionalProperty "tabs").
+    if (err.keyword === 'additionalProperties') {
+      const extra =
+        (err.params as { additionalProperty?: string }).additionalProperty;
+      return extra !== usedKey;
+    }
+    return true;
+  });
+}
+
 /**
  * Format validation errors into user-friendly messages
  */
-export function formatValidationErrors(errors: ErrorObject[] | null | undefined): string {
+export function formatValidationErrors(errors: ErrorObject[] | null | undefined, navigation?: Record<string, unknown>): string {
   if (!errors || errors.length === 0) {
     return 'Unknown validation error';
   }
@@ -270,8 +325,9 @@ export function formatValidationErrors(errors: ErrorObject[] | null | undefined)
   // Safe only because validateConfig pre-checks `config.theme` before Ajv,
   // so a fully-noise error list is unreachable in practice. A new caller
   // that skips the theme pre-check would break this invariant.
-  const filteredErrors = filterAnyOfNoise(errors);
-  const effectiveErrors = filteredErrors.length > 0 ? filteredErrors : errors;
+  const navFiltered = filterNavigationAnyOfNoise(errors, navigation);
+  const filteredErrors = filterAnyOfNoise(navFiltered);
+  const effectiveErrors = filteredErrors.length > 0 ? filteredErrors : navFiltered;
 
   const messages = effectiveErrors.slice(0, 3).map(err => {
     const path = err.instancePath || 'root';
@@ -548,7 +604,10 @@ export async function validateConfig(
       const valid = validate(config);
       
       if (!valid) {
-        const errorMessage = formatValidationErrors(validate.errors);
+        const errorMessage = formatValidationErrors(
+          validate.errors,
+          config.navigation as Record<string, unknown> | undefined,
+        );
         return {
           valid: false,
           error: `Invalid docs.json: ${errorMessage}`,