@conduction/docusaurus-preset 3.6.2 → 3.7.1

package/bin/validate-ai-baseline.mjs

@@ -87,25 +87,31 @@ check('sitemap.xml exists and has at least 1 URL', () => {
   return {ok: true, msg: `${n} URLs`};
 });
 
-/* sitemap.xml lastmod check is informational only. Google treats
-   lastmod as the only sitemap-level signal that actually informs
-   recrawl priority, but applying it requires per-site docusaurus.config
-   changes (sites that override `presets:` don't pick up the preset's
-   DEFAULT_SITEMAP_OPTIONS automatically). Warning here surfaces the
-   gap without blocking deploy on fleet sites that haven't adopted
-   the new sitemap config yet. Promote back to hard-fail in a future
-   release once the preset wraps user presets to inject sitemap defaults
-   automatically. */
-check('sitemap.xml emits <lastmod> on URLs (advisory, not fatal)', () => {
+/* sitemap.xml should ship <lastmod> on the majority of URLs. Google
+   treats lastmod as the only sitemap-level signal that actually informs
+   recrawl priority, and only when it's trustworthy. Preset 3.7+ wraps
+   user-supplied opts.presets to inject DEFAULT_SITEMAP_OPTIONS
+   (lastmod: 'date') into any classic preset entry, so every site that
+   bumps should see lastmod automatically.
+
+   Hard-fail when lastmod is missing entirely (means the preset wrap
+   didn't kick in). Pass when at least half of URLs have lastmod —
+   Docusaurus' auto-generated routes (/docs/category/X/, the root path
+   without a source file, redirects, etc.) legitimately don't have a
+   git mtime to use, so 100% coverage is unrealistic. ~80% is typical
+   for a content-heavy docs site. */
+check('sitemap.xml emits <lastmod> on URLs', () => {
   const body = readBuild('sitemap.xml');
   const locCount = (body.match(/<loc>/g) || []).length;
   const lastmodCount = (body.match(/<lastmod>/g) || []).length;
   if (locCount === 0) return {ok: false, msg: 'no <loc> entries to compare against'};
   if (lastmodCount === 0) {
-    /* Surface as a "passed with note" rather than fail. */
-    return {ok: true, msg: `WARN 0 / ${locCount} URLs have <lastmod> (enable sitemap.lastmod in docusaurus.config)`};
+    return {ok: false, msg: `0 / ${locCount} URLs have <lastmod>. Upgrade to @conduction/docusaurus-preset ^3.7.0 or set sitemap.lastmod in docusaurus.config.`};
   }
   const ratio = lastmodCount / locCount;
+  if (ratio < 0.5) {
+    return {ok: false, msg: `only ${lastmodCount} / ${locCount} URLs have <lastmod> (under 50%); investigate which routes are missing source files`};
+  }
   return {ok: true, msg: `${lastmodCount} / ${locCount} URLs (${Math.round(ratio * 100)}%)`};
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/docusaurus-preset",
-  "version": "3.6.2",
+  "version": "3.7.1",
   "scripts": {
     "prepack": "node scripts/prepack-bundle-css.js"
   },

package/src/index.js

@@ -292,6 +292,41 @@ const I18N = {
   },
 };
 
+/**
+ * Wrap a user-supplied `opts.presets` array so the classic preset's
+ * `sitemap` option inherits brand defaults (lastmod, ignorePatterns)
+ * when the site hasn't set them explicitly. Before this helper, sites
+ * that passed their own presets array silently lost the preset's
+ * DEFAULT_SITEMAP_OPTIONS, so the fleet sitemaps never shipped
+ * <lastmod> tags despite the preset claiming to add them. See
+ * MEMORY.md project_preset-4.0-wrap-user-presets for the back story.
+ *
+ * Recognises both 'classic' and '@docusaurus/preset-classic' entries.
+ * Leaves non-classic presets untouched. Explicit user values win:
+ * `sitemap: null` opts out, `sitemap: { lastmod: false }` opts out
+ * of lastmod specifically, and so on.
+ */
+function wrapClassicPresetDefaults(userPresets) {
+  return userPresets.map(entry => {
+    if (!Array.isArray(entry)) return entry;
+    const [name, config] = entry;
+    const isClassic =
+      name === 'classic' || name === '@docusaurus/preset-classic';
+    if (!isClassic || typeof config !== 'object' || config === null) return entry;
+    if (config.sitemap === null) return entry; /* explicit opt-out */
+    return [
+      name,
+      {
+        ...config,
+        sitemap: {
+          ...DEFAULT_SITEMAP_OPTIONS,
+          ...(config.sitemap || {}),
+        },
+      },
+    ];
+  });
+}
+
 /**
  * Brand-default navbar. Sites pass their own items[] and logo; the chrome
  * styling (cobalt-on-white, Plex-Mono caption) is locked.
@@ -476,30 +511,34 @@ function createConfig(opts) {
 
     i18n: opts.i18n || I18N,
 
-    presets: opts.presets || [
-      [
-        'classic',
-        {
-          docs: {
-            sidebarPath: './sidebars.js',
-            editUrl: opts.editUrl,
-          },
-          blog: opts.blog === false ? false : {
-            showReadingTime: true,
-            blogTitle: opts.title + ' blog',
-            blogDescription: 'Updates from Conduction',
-          },
-          theme: {
-            customCss,
-          },
-          /* AI-crawler-friendly defaults for @docusaurus/plugin-sitemap.
-             Per-locale sitemap.xml emitted automatically; /academy/tags
-             excluded across every locale prefix. Sites passing their own
-             presets array must include their own sitemap config too. */
-          sitemap: DEFAULT_SITEMAP_OPTIONS,
-        },
-      ],
-    ],
+    /* Sites can pass `opts.presets` to override docs/blog/theme. When
+       they do, the preset wraps each classic preset entry to deep-merge
+       DEFAULT_SITEMAP_OPTIONS into the entry's sitemap key (lastmod
+       becomes automatic, ignorePatterns merge in). Without this wrap
+       sites would have to copy-paste the sitemap config in every
+       docusaurus.config.js, and the fleet would drift over time. */
+    presets: opts.presets
+      ? wrapClassicPresetDefaults(opts.presets)
+      : [
+          [
+            'classic',
+            {
+              docs: {
+                sidebarPath: './sidebars.js',
+                editUrl: opts.editUrl,
+              },
+              blog: opts.blog === false ? false : {
+                showReadingTime: true,
+                blogTitle: opts.title + ' blog',
+                blogDescription: 'Updates from Conduction',
+              },
+              theme: {
+                customCss,
+              },
+              sitemap: DEFAULT_SITEMAP_OPTIONS,
+            },
+          ],
+        ],
 
     /* Brand theme: registers ./theme/* swizzles (Navbar, Footer, …)
        and auto-loads brand.css. Site-specific themes can be added by
@@ -581,15 +620,34 @@ function createConfig(opts) {
           opts.legalLinks || {}
         ),
         /* AI-friendly social-card defaults. `image` ships from the
-           preset's static/img/og-conduction.png and gets served at every
-           consuming site's /img/og-conduction.png; drop your own
-           static/img/og-conduction.png to override per-site. `metadata`
-           seeds twitter:site + twitter:card + og:type baselines; per-
-           page MDX frontmatter still wins via Helmet de-dupe. */
-        image: DEFAULT_OG_IMAGE,
-        metadata: DEFAULT_METADATA,
+           preset's static/img/og-conduction.png and gets served at
+           every consuming site's /img/og-conduction.png; drop your
+           own static/img/og-conduction.png to override per-site, or
+           pass `themeConfig.image: 'img/og-my-app.png'` to use a
+           different file. `metadata` seeds twitter:site + twitter:card
+           + og:type baselines; per-page MDX frontmatter still wins
+           via Helmet de-dupe.
+
+           These two slots are handled below via explicit overrides
+           rather than the wholesale Object.assign so that user-set
+           metadata extends (rather than replaces) the brand defaults
+           and image falls back gracefully. */
+        image: opts.themeConfig?.image || DEFAULT_OG_IMAGE,
+        metadata: [
+          ...DEFAULT_METADATA,
+          ...(opts.themeConfig?.metadata || []),
+        ],
       },
-      opts.themeConfig || {}
+      /* Object.assign last so opts.themeConfig overrides primitives
+         like colorMode and navbar, but the image + metadata keys
+         above pre-merged the user's values so the spread doesn't
+         clobber the brand defaults. */
+      (() => {
+        if (!opts.themeConfig) return {};
+        /* eslint-disable-next-line no-unused-vars */
+        const {image: _image, metadata: _metadata, ...rest} = opts.themeConfig;
+        return rest;
+      })()
     ),
 
     /* AI-crawler discovery: Organization + WebSite JSON-LD on every