@koehler8/cms 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.3.0
+
+### Added
+
+- **`meta.lastmod` — a page can date its own sitemap entry.** `buildSitemap`
+  now emits `<lastmod>` for any page supplying `meta.lastmod`, as either a
+  complete date (`2026-09-06`) or a full ISO 8601 timestamp
+  (`2026-09-06T14:30:00Z`). All locale variants of a page inherit it — a
+  translation of a page is the same page.
+
+  This matters most for sites that publish on a cadence. Without `lastmod` a
+  crawler has no priority signal distinguishing the piece published last night
+  from one published in May, and has to rediscover that by fetching. On the
+  publication this was built for, Search Console reported **490 URLs
+  "Discovered - currently not indexed" with `Last crawled: N/A`** — found in the
+  sitemap and never fetched at all.
+
+  **The framework never derives a date.** Build time is not modification time,
+  and a sitemap whose `lastmod` moves on every deploy is one search engines
+  learn to ignore — Google's stated rule is that it must be consistently
+  accurate or it is disregarded. Only the site knows when its content actually
+  changed, so only the site can say.
+
+  A malformed value (`2026`, `09/06/2026`, `2026-02-30`, a `Date`, a number) is
+  dropped rather than emitted: an invalid `lastmod` invalidates the whole
+  `<url>` entry for some parsers, which is worse than having none.
+  `normalizeLastmod` is exported for sites that want to validate before writing.
+
+  Output for pages that omit `meta.lastmod` is unchanged, so existing sites see
+  no diff.
+
 ## 1.2.0
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",

package/src/utils/sitemapGenerator.js

@@ -14,6 +14,16 @@
  * <xhtml:link rel="alternate" hreflang="..." /> cluster plus an `x-default`
  * pointing at the base-locale URL. The single-locale output stays
  * byte-identical to pre-hreflang.
+ *
+ * <lastmod> is emitted for a page only when it supplies `meta.lastmod`, as
+ * either a date (YYYY-MM-DD) or a full ISO 8601 timestamp. The framework never
+ * derives one: build time is not modification time, and a sitemap whose
+ * lastmod moves on every deploy is one search engines learn to ignore
+ * (Google's stated rule is that it must be consistently accurate). A page that
+ * omits it is emitted exactly as before, so existing sites are unchanged.
+ *
+ * All locale variants of a page share its lastmod — a translation of a page is
+ * the same page, and the site is the only thing that knows otherwise.
  */
 
 import { isPathDraft, normalizeDraftPath } from './draftMode.js';
@@ -30,6 +40,33 @@ function escapeXml(value) {
   }[c]));
 }
 
+// W3C Datetime, the subset the sitemap protocol allows: a complete date, or a
+// complete date plus hours/minutes/seconds and a timezone. Anything else — a
+// bare year, a US-format date, a Date object stringified, a number — is
+// dropped rather than emitted, because a malformed lastmod invalidates the
+// <url> entry for some parsers and is worse than none at all.
+const LASTMOD_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const LASTMOD_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+
+export function normalizeLastmod(value) {
+  if (typeof value !== 'string') return '';
+  const raw = value.trim();
+  if (!raw) return '';
+  if (!LASTMOD_DATE.test(raw) && !LASTMOD_DATETIME.test(raw)) return '';
+  // Shape-valid but not a real day (2026-02-30, month 13) — Date rolls those
+  // over silently, so compare the round-trip rather than trusting the parse.
+  const [y, m, d] = raw.slice(0, 10).split('-').map(Number);
+  const probe = new Date(Date.UTC(y, m - 1, d));
+  if (
+    probe.getUTCFullYear() !== y ||
+    probe.getUTCMonth() !== m - 1 ||
+    probe.getUTCDate() !== d
+  ) {
+    return '';
+  }
+  return raw;
+}
+
 export function buildSitemap(siteConfig, options = {}) {
   const siteUrl = (siteConfig?.site?.url || '').trim().replace(/\/+$/, '');
   if (!siteUrl) return '';
@@ -65,8 +102,10 @@ export function buildSitemap(siteConfig, options = {}) {
     const baseUrl = buildCanonicalUrl({ siteUrl, baseLocale, locale: baseLocale, path: pagePath, trailingSlash });
     if (!baseUrl) continue;
 
+    const lastmod = normalizeLastmod(pageData?.meta?.lastmod);
+
     if (!isMultiLocale) {
-      entries.push({ loc: baseUrl, alternates: [] });
+      entries.push({ loc: baseUrl, alternates: [], lastmod });
       continue;
     }
 
@@ -81,7 +120,7 @@ export function buildSitemap(siteConfig, options = {}) {
 
     for (const loc of availableLocales) {
       const localizedUrl = buildCanonicalUrl({ siteUrl, baseLocale, locale: loc, path: pagePath, trailingSlash });
-      if (localizedUrl) entries.push({ loc: localizedUrl, alternates });
+      if (localizedUrl) entries.push({ loc: localizedUrl, alternates, lastmod });
     }
   }
 
@@ -94,13 +133,24 @@ export function buildSitemap(siteConfig, options = {}) {
     : 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"';
 
   const renderUrlEntry = (entry) => {
+    // <lastmod> follows <loc> and precedes the alternates: the sitemap XSD
+    // sequences loc, lastmod, changefreq, priority, and xhtml:link extensions
+    // are appended after those.
+    const lastmodLine = entry.lastmod
+      ? `\n    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`
+      : '';
+
     if (entry.alternates.length === 0) {
-      return `  <url><loc>${escapeXml(entry.loc)}</loc></url>`;
+      // Kept on one line when there is nothing else to emit, so single-locale
+      // sites with no lastmod stay byte-identical to previous versions.
+      return entry.lastmod
+        ? `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>${lastmodLine}\n  </url>`
+        : `  <url><loc>${escapeXml(entry.loc)}</loc></url>`;
     }
     const altLines = entry.alternates
       .map((a) => `    <xhtml:link rel="alternate" hreflang="${escapeXml(a.hreflang)}" href="${escapeXml(a.href)}"/>`)
       .join('\n');
-    return `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>\n${altLines}\n  </url>`;
+    return `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>${lastmodLine}\n${altLines}\n  </url>`;
   };
 
   const urlEntries = entries.map(renderUrlEntry).join('\n');