@conduction/docusaurus-preset 3.5.0 → 3.6.1

package/README.md

@@ -213,6 +213,35 @@ createConfig({
 });
 ```
 
+## Traditional SEO baseline
+
+The same `createConfig` call also wires the traditional-search baseline that pairs with the AI-crawler one. Google, Bing, DuckDuckGo and the AI surfaces those engines feed (Copilot, ChatGPT Search, Perplexity) all benefit.
+
+**What's shipped automatically**
+
+- **Sitemap with `lastmod`** from file mtime; `priority` and `changefreq` are dropped because Google ignores them. `/page/N/` pagination and `/academy/tags/` thin pages are excluded sitewide so they don't dilute crawl budget.
+- **Footer legal links default to absolute URLs on `www.conduction.nl`** (`/privacy`, `/terms`, `/iso`). Earlier defaults used relative routes that 404'd on every per-app subdomain — the SEO audit found ~645 sitewide broken internal links across the fleet from this single mistake. Marketing sites that self-host these pages pass `legalLinks: { privacy: '/privacy', ... }` to opt back into relative routing.
+- **Search Console / Bing Webmaster / Yandex / Facebook / Pinterest verification meta tags** via `opts.searchConsoleVerification`. Each present token becomes a `<meta>` tag in the global head, which lets a non-DNS-admin teammate verify the property via the console UI:
+
+```js
+createConfig({
+  // ...
+  searchConsoleVerification: {
+    google: 'abc123...',     // -> <meta name="google-site-verification">
+    bing:   'xyz...',        // -> <meta name="msvalidate.01">
+    yandex: '...',           // -> <meta name="yandex-verification">
+    facebook: '...',         // -> <meta name="facebook-domain-verification">
+    pinterest: '...',        // -> <meta name="p:domain_verify">
+  },
+});
+```
+
+**Known follow-ups (not yet automatic)**
+
+- `BreadcrumbList` JSON-LD on every page. The DocBreadcrumbs DOM already renders; the schema needs a theme swizzle. Tracked as a 3.7+ candidate.
+- `TechArticle` JSON-LD on docs pages with `dateModified` from git mtime. Same swizzle scope.
+- Per-page title format. Docusaurus defaults to `{Page} | {Site}` which produces `OpenRegister | OpenRegister` on per-app homepages. Override per page via frontmatter `title:` for now; a `titleFormat` option may land later.
+
 ## Releasing
 
 Releases auto-publish on push to `main`, driven by [semantic-release](https://semantic-release.gitbook.io/) reading [conventional-commit](https://www.conventionalcommits.org/) messages. The [.github/workflows/publish-packages.yml](../.github/workflows/publish-packages.yml) workflow walks every commit since the last `@conduction/docusaurus-preset-v*` tag and decides what to ship:

package/bin/validate-ai-baseline.mjs

@@ -87,6 +87,22 @@ check('sitemap.xml exists and has at least 1 URL', () => {
   return {ok: true, msg: `${n} URLs`};
 });
 
+/* sitemap.xml should ship <lastmod> on every URL. Google treats lastmod
+   as the only sitemap-level signal that actually informs recrawl
+   priority, and only when it's trustworthy. Sites that ship priority +
+   changefreq without lastmod (the Docusaurus default before preset
+   3.6.0) get treated as having no freshness signal. */
+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) return {ok: false, msg: `0 / ${locCount} URLs have <lastmod> — enable sitemap.lastmod in docusaurus.config`};
+  const ratio = lastmodCount / locCount;
+  if (ratio < 0.5) return {ok: false, msg: `only ${lastmodCount} / ${locCount} URLs have <lastmod>`};
+  return {ok: true, msg: `${lastmodCount} / ${locCount} URLs (${Math.round(ratio * 100)}%)`};
+});
+
 /* Helper for the JSON-LD checks below. Docusaurus emits ld+json
    tags via two paths with different attribute ordering: top-level
    headTags renders <script type="..."> first, while Helmet (used

package/package.json

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

package/src/index.js

@@ -160,7 +160,7 @@ function buildWebsiteJsonLd(opts) {
  * the site's tags after its own defaults.
  */
 function buildAiHeadTags(opts) {
-  return [
+  const tags = [
     {
       tagName: 'script',
       attributes: {type: 'application/ld+json'},
@@ -172,6 +172,45 @@ function buildAiHeadTags(opts) {
       innerHTML: JSON.stringify(buildWebsiteJsonLd(opts)),
     },
   ];
+
+  /* Search Console verification meta tags. Sites pass tokens via
+     opts.searchConsoleVerification = { google: '...', bing: '...',
+     yandex: '...' }; each present token becomes a meta tag. Verifying
+     via meta (vs DNS TXT) lets a non-DNS-admin teammate access Search
+     Console / Bing Webmaster Tools. */
+  const verification = opts.searchConsoleVerification || {};
+  if (verification.google) {
+    tags.push({
+      tagName: 'meta',
+      attributes: {name: 'google-site-verification', content: verification.google},
+    });
+  }
+  if (verification.bing) {
+    tags.push({
+      tagName: 'meta',
+      attributes: {name: 'msvalidate.01', content: verification.bing},
+    });
+  }
+  if (verification.yandex) {
+    tags.push({
+      tagName: 'meta',
+      attributes: {name: 'yandex-verification', content: verification.yandex},
+    });
+  }
+  if (verification.facebook) {
+    tags.push({
+      tagName: 'meta',
+      attributes: {name: 'facebook-domain-verification', content: verification.facebook},
+    });
+  }
+  if (verification.pinterest) {
+    tags.push({
+      tagName: 'meta',
+      attributes: {name: 'p:domain_verify', content: verification.pinterest},
+    });
+  }
+
+  return tags;
 }
 
 /**
@@ -184,15 +223,36 @@ function buildAiHeadTags(opts) {
  * Sites passing their own classic preset config can override by
  * including a `sitemap` key alongside `docs`/`blog`/`theme`.
  */
+/**
+ * Sitemap defaults. Google ignores `changefreq` and `priority` (and has
+ * for years; the @docusaurus/plugin-sitemap defaults are wrong on this
+ * point). `lastmod` is the only signal Google actually uses, and only
+ * if the dates are accurate, so we ship lastmod from file mtime. Bing
+ * still reads all three, harmless to omit.
+ *
+ * Sites with locale-specific tag pages and pagination should keep the
+ * exclude list in sync. Pagination (`/page/N/`) and tag pages
+ * (`/tags/{slug}/`) are documented Docusaurus duplicate-content traps;
+ * we exclude them by default so they neither dilute crawl budget nor
+ * confuse AI summarisers. (Do not write `/tags/*` followed by a slash
+ * in this comment: the literal asterisk-slash sequence would close
+ * the JSDoc block and break preset parsing for every consuming site.)
+ */
 const DEFAULT_SITEMAP_OPTIONS = {
-  changefreq: 'weekly',
-  priority: 0.5,
+  changefreq: null,
+  priority: null,
+  lastmod: 'date',
   ignorePatterns: [
     '/academy/tags/**',
     '/nl/academy/tags/**',
     '/en/academy/tags/**',
     '/de/academy/tags/**',
     '/fr/academy/tags/**',
+    '/page/**',
+    '/nl/page/**',
+    '/en/page/**',
+    '/de/page/**',
+    '/fr/page/**',
   ],
   filename: 'sitemap.xml',
 };
@@ -489,9 +549,15 @@ function createConfig(opts) {
         footerBrand: opts.footerBrand || null,
         /* Legal-bar links (Privacy / Terms / ISO) plus the two ISO
            9001 + 27001 certification badges on the right side of the
-           canal-footer. Default keeps prior behaviour (pages live at
-           /privacy, /terms, /iso on docs.conduction.nl + www.conduction.nl).
-           Consumer sites that don't ship those pages can opt out per
+           canal-footer.
+
+           Defaults point at the canonical Conduction pages on
+           www.conduction.nl rather than relative routes. Earlier
+           defaults used /privacy, /terms, /iso which 404'd on every
+           per-app subdomain (openregister.conduction.nl/privacy etc.)
+           because those routes only exist on the marketing site. The
+           SEO audit found ~645 sitewide broken internal links across
+           the fleet from this single mistake. Sites can override per
            slot to silence broken-link warnings:
 
              legalLinks: {
@@ -499,12 +565,21 @@ function createConfig(opts) {
                terms:   false,     // hide the Terms link
                iso:     false,     // hide the ISO link AND the cert badges
                                    // (badges follow iso link by default)
-               // any slot can also take a string for an external URL:
-               privacy: 'https://docs.conduction.nl/privacy',
-               // certs default-follow iso, override here:
-               isoCertifications: true | false,
-             } */
-        legalLinks: opts.legalLinks || {},
+               privacy: '/privacy', // self-host: pass a relative route
+               certifications: true | false,
+             }
+
+           The marketing site at conduction-website passes legalLinks
+           explicitly with relative routes so its self-hosted Privacy /
+           Terms / ISO pages keep working as before. */
+        legalLinks: Object.assign(
+          {
+            privacy: 'https://www.conduction.nl/privacy',
+            terms: 'https://www.conduction.nl/terms',
+            iso: 'https://www.conduction.nl/iso',
+          },
+          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