@redpanda-data/docs-extensions-and-macros 4.15.1 → 4.15.3

package/extensions/add-git-dates.js

@@ -0,0 +1,287 @@
+'use strict'
+
+/**
+ * Adds Git commit dates to pages as attributes.
+ *
+ * This extension:
+ * 1. Gets the first commit date (when file was created) -> page-git-created-date
+ * 2. Gets the last commit date (when file was modified) -> page-git-modified-date
+ * 3. Adds these to page.asciidoc.attributes with page- prefix for UI template access
+ *
+ * Supports both local repos (with worktree) and remote repos (bare clones with gitdir).
+ * Antora caches remote repos as bare Git repos in ~/.cache/antora/content/
+ *
+ * Performance optimization: Uses isomorphic-git to walk the entire git log ONCE per
+ * repository, building a filepath→dates map. This is O(commits) instead of O(files * commits).
+ * For a repo with 1000 files and 5000 commits, this reduces operations from 5M to 5K.
+ *
+ * Attribute naming: Uses page- prefix so attributes appear in page.attributes
+ * in Handlebars templates (Antora strips the prefix when exposing to UI model).
+ *
+ * Only runs on pages that have origin info (skips virtual/generated pages).
+ */
+
+const path = require('path')
+const fs = require('fs')
+
+/**
+ * Resolve isomorphic-git from Antora's dependencies
+ * @param {Object} context - Extension context with module info
+ * @returns {Object} isomorphic-git module
+ */
+function requireGit (context) {
+  return require(
+    require.resolve('isomorphic-git', {
+      paths: [require.resolve('@antora/content-aggregator', { paths: context.module.paths }) + '/..']
+    })
+  )
+}
+
+/**
+ * Format timestamp to ISO date string (YYYY-MM-DD)
+ * @param {number} timestamp - Unix timestamp in seconds
+ * @returns {string} ISO date string
+ */
+function formatDate (timestamp) {
+  return new Date(timestamp * 1000).toISOString().substring(0, 10)
+}
+
+/**
+ * Build a map of filepath -> {created, modified} dates from git log
+ * Walks the entire log once, tracking first and last commit for each MODIFIED file
+ *
+ * This compares each commit's tree with its parent to find which files actually changed,
+ * rather than just looking at all files in the tree (which would give incorrect dates).
+ *
+ * @param {Object} git - isomorphic-git module
+ * @param {string} gitdir - Path to .git directory
+ * @param {string} ref - Git ref (branch/tag/commit)
+ * @param {Object} logger - Logger instance
+ * @returns {Promise<Map<string, {created: string, modified: string}>>}
+ */
+async function buildFileDateMap (git, gitdir, ref, logger) {
+  const fileDates = new Map()
+  const cache = {}
+
+  try {
+    // Get all commits - walking from newest to oldest
+    const commits = await git.log({
+      fs,
+      gitdir,
+      ref,
+      cache,
+    })
+
+    logger.info(`Walking ${commits.length} commits for ${path.basename(gitdir)} (ref: ${ref})`)
+
+    // Build tree cache to avoid re-reading trees
+    const treeCache = new Map()
+
+    // Process commits from newest to oldest
+    // First occurrence = modified date, last occurrence = created date
+    for (let i = 0; i < commits.length; i++) {
+      const commit = commits[i]
+      const timestamp = commit.commit.committer.timestamp
+      const date = formatDate(timestamp)
+
+      try {
+        const currentTreeOid = commit.commit.tree
+        const parentCommits = commit.commit.parent || []
+
+        // Get files in current commit's tree
+        const currentFiles = await getTreeFiles(git, gitdir, currentTreeOid, '', cache, treeCache)
+
+        // Get files in parent commit's tree (if parent exists)
+        let parentFiles = new Map()
+        if (parentCommits.length > 0) {
+          const parentCommit = await git.readCommit({ fs, gitdir, oid: parentCommits[0], cache })
+          const parentTreeOid = parentCommit.commit.tree
+          parentFiles = await getTreeFiles(git, gitdir, parentTreeOid, '', cache, treeCache)
+        }
+
+        // Find files that were added or modified (different OID from parent)
+        for (const [filepath, oid] of currentFiles) {
+          const parentOid = parentFiles.get(filepath)
+          const isModified = !parentOid || parentOid !== oid
+
+          if (isModified) {
+            if (!fileDates.has(filepath)) {
+              // First time seeing this file modified (from newest commit)
+              fileDates.set(filepath, { created: date, modified: date })
+            } else {
+              // Update created date (older commit where file was modified)
+              const entry = fileDates.get(filepath)
+              entry.created = date
+            }
+          }
+        }
+      } catch (err) {
+        // Skip commits that can't be read
+        logger.debug(`Skipping commit ${commit.oid.substring(0, 7)}: ${err.message}`)
+      }
+    }
+  } catch (err) {
+    logger.warn(`Failed to read git log for ${gitdir}: ${err.message}`)
+  }
+
+  return fileDates
+}
+
+/**
+ * Recursively walk a git tree to get all file paths with their OIDs
+ * Returns a Map of filepath → OID for comparison between commits
+ *
+ * @param {Object} git - isomorphic-git module
+ * @param {string} gitdir - Path to .git directory
+ * @param {string} oid - Tree object ID
+ * @param {string} prefix - Current path prefix
+ * @param {Object} cache - Git object cache
+ * @param {Map} treeCache - Cache of tree OID → files map
+ * @returns {Promise<Map<string, string>>} Map of filepath → blob OID
+ */
+async function getTreeFiles (git, gitdir, oid, prefix, cache, treeCache) {
+  // Check tree cache first
+  if (treeCache.has(oid)) {
+    return treeCache.get(oid)
+  }
+
+  const files = new Map()
+
+  try {
+    const { tree } = await git.readTree({
+      fs,
+      gitdir,
+      oid,
+      cache,
+    })
+
+    for (const entry of tree) {
+      const filepath = prefix ? `${prefix}/${entry.path}` : entry.path
+
+      if (entry.type === 'blob') {
+        files.set(filepath, entry.oid)
+      } else if (entry.type === 'tree') {
+        // Recurse into subdirectory
+        const subfiles = await getTreeFiles(git, gitdir, entry.oid, filepath, cache, treeCache)
+        for (const [subpath, suboid] of subfiles) {
+          files.set(subpath, suboid)
+        }
+      }
+    }
+
+    // Cache this tree's files
+    treeCache.set(oid, files)
+  } catch (err) {
+    // Skip trees that can't be read
+  }
+
+  return files
+}
+
+module.exports.register = function () {
+  const logger = this.getLogger('add-git-dates-extension')
+  const context = this
+
+  // Run on documentsConverted after Antora builds page.asciidoc.attributes
+  this.on('documentsConverted', async ({ contentCatalog }) => {
+    const startTime = Date.now()
+    let processedCount = 0
+    let skippedCount = 0
+
+    // Load isomorphic-git
+    let git
+    try {
+      git = requireGit(context)
+    } catch (err) {
+      logger.error(`Failed to load isomorphic-git: ${err.message}`)
+      return
+    }
+
+    // Group pages by BOTH gitdir AND ref (since same repo can have multiple branches/versions)
+    const pagesByRepoAndRef = new Map()
+    const skipLoggedRepos = new Set()
+
+    contentCatalog.getPages().forEach((page) => {
+      const origin = page.src?.origin
+      if (!origin?.url) {
+        skippedCount++
+        return
+      }
+
+      // Need gitdir for isomorphic-git (works for both local and bare repos)
+      const gitdir = origin.gitdir || (origin.worktree ? path.join(origin.worktree, '.git') : null)
+      if (!gitdir) {
+        // Debug: Log which repos don't have gitdir
+        if (!skipLoggedRepos.has(origin.url)) {
+          logger.info(`⚠️  Skipping repo without gitdir: ${origin.url} (has gitdir: ${!!origin.gitdir}, has worktree: ${!!origin.worktree})`)
+          skipLoggedRepos.add(origin.url)
+        }
+        skippedCount++
+        return
+      }
+
+      // Ensure asciidoc.attributes exists
+      if (!page.asciidoc) page.asciidoc = {}
+      if (!page.asciidoc.attributes) page.asciidoc.attributes = {}
+
+      const startPath = origin.startPath || ''
+      const relativeFilePath = startPath ? path.join(startPath, page.src.path) : page.src.path
+      const ref = origin.refhash || origin.refname || 'HEAD'
+
+      // Create composite key: gitdir + ref to handle multiple branches per repo
+      const repoRefKey = `${gitdir}::${ref}`
+
+      // Group by repo AND ref
+      if (!pagesByRepoAndRef.has(repoRefKey)) {
+        pagesByRepoAndRef.set(repoRefKey, {
+          gitdir,
+          ref,
+          pages: []
+        })
+      }
+      pagesByRepoAndRef.get(repoRefKey).pages.push({ page, relativeFilePath })
+    })
+
+    const totalPages = Array.from(pagesByRepoAndRef.values()).reduce((sum, r) => sum + r.pages.length, 0)
+    const repoCount = new Set(Array.from(pagesByRepoAndRef.values()).map(r => r.gitdir)).size
+    logger.info(`Processing ${totalPages} pages across ${repoCount} repos (${pagesByRepoAndRef.size} branches) for git dates (skipped ${skippedCount} virtual/generated)`)
+
+    // Log which repos are being processed
+    const reposBeingProcessed = new Set()
+    pagesByRepoAndRef.forEach(({ gitdir }) => {
+      if (!reposBeingProcessed.has(gitdir)) {
+        logger.info(`✓ Will process git dates for: ${gitdir}`)
+        reposBeingProcessed.add(gitdir)
+      }
+    })
+
+    // Process each repository + ref combination
+    for (const [repoRefKey, { gitdir, ref, pages }] of pagesByRepoAndRef) {
+      const repoStartTime = Date.now()
+
+      try {
+        // Build the filepath -> dates map for this repo + ref
+        const fileDateMap = await buildFileDateMap(git, gitdir, ref, logger)
+
+        // Apply dates to pages
+        for (const { page, relativeFilePath } of pages) {
+          const dates = fileDateMap.get(relativeFilePath)
+          if (dates) {
+            page.asciidoc.attributes['page-git-created-date'] = dates.created
+            page.asciidoc.attributes['page-git-modified-date'] = dates.modified
+            processedCount++
+          }
+        }
+
+        const repoTime = Date.now() - repoStartTime
+        logger.debug(`Processed ${pages.length} pages from ${path.basename(gitdir)}@${ref.substring(0,8)} in ${repoTime}ms (map size: ${fileDateMap.size})`)
+      } catch (err) {
+        logger.warn(`Failed to process repo ${gitdir}@${ref}: ${err.message}`)
+      }
+    }
+
+    const duration = Date.now() - startTime
+    const perPage = totalPages > 0 ? (duration / totalPages).toFixed(1) : 0
+    logger.info(`Git dates added: processed=${processedCount}, skipped=${skippedCount}, duration=${duration}ms (${perPage}ms/page)`)
+  })
+}

package/extensions/convert-llms-to-txt.js

@@ -1,7 +1,9 @@
 'use strict';
 
+const { toMarkdownUrl } = require('../extension-utils/url-utils');
+
 /**
- * Extracts markdown from llms.adoc page and generates llms.txt and llms-full.txt.
+ * Extracts markdown from llms.adoc page and generates AI-friendly documentation exports.
  *
  * This extension:
  * 1. Adds site-url attribute to home component:
@@ -11,7 +13,8 @@
  * 3. Gets the markdown content from page.markdownContents (set by convert-to-markdown extension)
  * 4. Unpublishes the HTML page
  * 5. Places llms.txt (markdown) at site root
- * 6. Generates llms-full.txt with markdown from latest versions
+ * 6. Generates llms-full.txt with markdown from latest versions of all components
+ * 7. Generates component-specific full.txt files (e.g., redpanda-full.txt, cloud-full.txt)
  *
  * Must run after convert-to-markdown extension to access page.markdownContents.
  */
@@ -73,13 +76,16 @@ module.exports.register = function () {
         content = content.replace(/^<!--[\s\S]*?-->\s*/gm, '').trim();
         logger.debug(`Stripped HTML comments, now ${content.length} bytes`);
 
-        // Fix URLs: convert em dashes back to double hyphens
+        // Fix URLs: convert em dashes back to double hyphens and remove invisible characters
         // The markdown converter applies smart typography that turns -- into — (em dash)
+        // and inserts zero-width spaces (U+200B) and other invisible Unicode characters
         // This breaks URLs like deploy-preview-159--redpanda-documentation.netlify.app
-        content = content.replace(/\(https?:\/\/[^)]*—[^)]*\)/g, (match) => {
-          return match.replace(/—/g, '--');
+        content = content.replace(/\(https?:\/\/[^)]*[—\u200B-\u200D\uFEFF][^)]*\)/g, (match) => {
+          return match
+            .replace(/—/g, '--')
+            .replace(/[\u200B-\u200D\uFEFF]/g, '');
         });
-        logger.debug('Fixed em dashes in URLs');
+        logger.debug('Fixed em dashes and invisible characters in URLs');
 
         // Unpublish the HTML page FIRST (following unpublish-pages pattern)
         if (llmsPage.out) {
@@ -143,6 +149,15 @@ module.exports.register = function () {
       }
     });
     fullContent += `\n`;
+    fullContent += `### AI-Friendly Documentation Formats\n\n`;
+    fullContent += `We provide multiple formats optimized for AI consumption:\n\n`;
+    fullContent += `- **${siteUrl}/llms.txt**: Curated overview following the llms.txt standard - start here for a quick introduction\n`;
+    fullContent += `- **${siteUrl}/llms-full.txt**: Complete documentation export (this file) - comprehensive reference with all pages\n`;
+    fullContent += `- **Component-specific exports**: Focused documentation for individual products:\n`;
+    components.forEach(component => {
+      fullContent += `  - \`${siteUrl}/${component.name}-full.txt\`: ${component.title}\n`;
+    });
+    fullContent += `- **Individual markdown pages**: Each HTML page has a corresponding .md file (e.g., \`/docs/page.html\` → \`/docs/page.md\`)\n\n`;
     fullContent += `### Accessing Versioned Content\n\n`;
     fullContent += `For components with versioned documentation (like Redpanda Self-Managed), older versions can be accessed by replacing the version segment in the URL:\n`;
     fullContent += `- Latest: \`${siteUrl}/current/page-path\`\n`;
@@ -158,7 +173,8 @@ module.exports.register = function () {
     });
 
     pages.forEach((page, index) => {
-      const pageUrl = page.pub?.url ? `${siteUrl}${page.pub.url}` : 'unknown';
+      const mdUrl = page.pub?.url ? toMarkdownUrl(page.pub.url) : '';
+      const pageUrl = mdUrl ? `${siteUrl}${mdUrl}` : 'unknown';
       const pageTitle = page.asciidoc?.doctitle || page.src?.stem || 'Untitled';
 
       fullContent += `# Page ${index + 1}: ${pageTitle}\n\n`;
@@ -175,16 +191,334 @@ module.exports.register = function () {
     });
     logger.info(`Generated llms-full.txt with ${pages.length} pages`);
 
+    // Generate component-specific full.txt files
+    logger.info('Generating component-specific full.txt files...');
+    const componentGroups = new Map();
+
+    // Group pages by component
+    pages.forEach(page => {
+      const componentName = page.src.component;
+      if (!componentGroups.has(componentName)) {
+        componentGroups.set(componentName, []);
+      }
+      componentGroups.get(componentName).push(page);
+    });
+
+    // Generate a full.txt file for each component
+    componentGroups.forEach((componentPages, componentName) => {
+      const component = components.find(c => c.name === componentName);
+      if (!component) return;
+
+      const latest = component.latest || component.versions[0];
+      if (!latest) return;
+
+      // Sort pages by URL for consistent ordering
+      componentPages.sort((a, b) => {
+        const urlA = a.pub?.url || '';
+        const urlB = b.pub?.url || '';
+        return urlA.localeCompare(urlB);
+      });
+
+      let componentContent = `# ${component.title} - Full Markdown Export\n\n`;
+      componentContent += `> This file contains all ${component.title} documentation pages in markdown format for AI agent consumption.\n`;
+      componentContent += `> Generated from ${componentPages.length} pages on ${new Date().toISOString()}\n`;
+      componentContent += `> Component: ${component.name} | Version: ${latest.version}\n`;
+      componentContent += `> Site: ${siteUrl}\n\n`;
+      componentContent += `## About This Export\n\n`;
+      componentContent += `This export includes the **latest version** (${latest.version}) of the ${component.title} documentation.\n\n`;
+      componentContent += `### AI-Friendly Documentation Formats\n\n`;
+      componentContent += `We provide multiple formats optimized for AI consumption:\n\n`;
+      componentContent += `- **${siteUrl}/llms.txt**: Curated overview of all Redpanda documentation\n`;
+      componentContent += `- **${siteUrl}/llms-full.txt**: Complete documentation export with all components\n`;
+      componentContent += `- **${siteUrl}/${componentName}-full.txt**: This file - ${component.title} documentation only\n`;
+      componentContent += `- **Individual markdown pages**: Each HTML page has a corresponding .md file\n\n`;
+
+      if (component.versions.length > 1) {
+        componentContent += `### Accessing Older Versions\n\n`;
+        componentContent += `This component has versioned documentation. Older versions can be accessed by replacing the version segment in the URL:\n`;
+        componentContent += `- Latest: \`${siteUrl}/current/page-path\`\n`;
+        componentContent += `- Specific version: \`${siteUrl}/24.3/page-path\`, \`${siteUrl}/25.1/page-path\`, etc.\n\n`;
+      }
+
+      componentContent += `---\n\n`;
+
+      // Add all pages
+      componentPages.forEach((page, index) => {
+        const mdUrl = page.pub?.url ? toMarkdownUrl(page.pub.url) : '';
+        const pageUrl = mdUrl ? `${siteUrl}${mdUrl}` : 'unknown';
+        const pageTitle = page.asciidoc?.doctitle || page.src?.stem || 'Untitled';
+
+        componentContent += `# Page ${index + 1}: ${pageTitle}\n\n`;
+        componentContent += `**URL**: ${pageUrl}\n\n`;
+        componentContent += `---\n\n`;
+        componentContent += page.markdownContents.toString('utf8');
+        componentContent += `\n\n---\n\n`;
+      });
+
+      // Add component-specific full.txt file to site root
+      siteCatalog.addFile({
+        contents: Buffer.from(componentContent, 'utf8'),
+        out: { path: `${componentName}-full.txt` },
+      });
+      logger.info(`Generated ${componentName}-full.txt with ${componentPages.length} pages`);
+    });
+
     // Add llms.txt to site root (using content extracted earlier)
     if (llmsPage && llmsPage.llmsTxtContent) {
       logger.info('Adding llms.txt to site root');
+
       siteCatalog.addFile({
         contents: Buffer.from(llmsPage.llmsTxtContent, 'utf8'),
         out: { path: 'llms.txt' },
       });
       logger.info('Successfully added llms.txt');
+
+      // Add llms.txt to sitemap with git dates
+      try {
+        // Build a map of filename -> most recent git modified date
+        const gitDates = new Map();
+
+        // llms.txt uses the llms page's git modified date
+        if (llmsPage.asciidoc?.attributes?.['page-git-modified-date']) {
+          gitDates.set('llms.txt', llmsPage.asciidoc.attributes['page-git-modified-date']);
+        }
+
+        // llms-full.txt uses the most recent modified date from all pages
+        if (pages.length > 0) {
+          const mostRecent = getMostRecentGitDate(pages);
+          if (mostRecent) {
+            gitDates.set('llms-full.txt', mostRecent);
+          }
+        }
+
+        // Component-specific files use most recent from that component
+        componentGroups.forEach((componentPages, componentName) => {
+          const mostRecent = getMostRecentGitDate(componentPages);
+          if (mostRecent) {
+            gitDates.set(`${componentName}-full.txt`, mostRecent);
+          }
+        });
+
+        addToSitemap(contentCatalog, siteCatalog, siteUrl, gitDates, logger);
+      } catch (err) {
+        logger.warn(`Failed to add llms.txt to sitemap: ${err.message}`);
+      }
     } else {
       logger.warn('llms.txt not generated - page not found or no content extracted');
     }
   });
 };
+
+/**
+ * Get the most recent git modified date from a collection of pages
+ */
+function getMostRecentGitDate(pages) {
+  let mostRecent = null;
+
+  for (const page of pages) {
+    const gitDate = page.asciidoc?.attributes?.['page-git-modified-date'];
+    if (gitDate) {
+      const date = new Date(gitDate);
+      if (!mostRecent || date > mostRecent) {
+        mostRecent = date;
+      }
+    }
+  }
+
+  return mostRecent ? mostRecent.toISOString() : null;
+}
+
+/**
+ * Add llms.txt and all -full.txt files to sitemap by creating a separate sitemap-llms.xml
+ * and adding it to the main sitemap index
+ *
+ * @param {Object} contentCatalog - Antora content catalog (source pages)
+ * @param {Object} siteCatalog - Antora site catalog (output files)
+ * @param {string} siteUrl - Base site URL
+ * @param {Map<string, string>} gitDates - Map of filename -> ISO date string from git history
+ * @param {Object} logger - Logger instance
+ */
+function addToSitemap(contentCatalog, siteCatalog, siteUrl, gitDates, logger) {
+  const now = new Date().toISOString();
+
+  // Find all llms .txt files in the site catalog
+  const llmsFiles = siteCatalog.getFiles()
+    .filter(file => {
+      const filename = file.out.path;
+      return filename === 'llms.txt' ||
+             filename === 'llms-full.txt' ||
+             filename.endsWith('-full.txt');
+    })
+    .map(file => file.out.path)
+    .sort(); // Sort for consistent ordering
+
+  logger.info(`Found ${llmsFiles.length} llms files to add to sitemap: ${llmsFiles.join(', ')}`);
+
+  // Create sitemap-llms.xml with all llms files
+  const urlEntries = llmsFiles.map(filename => {
+    // Use git date if available, otherwise fall back to build time
+    const lastmod = gitDates.get(filename) || now;
+    return `  <url>
+    <loc>${siteUrl}/${filename}</loc>
+    <lastmod>${lastmod}</lastmod>
+    <changefreq>daily</changefreq>
+    <priority>1.0</priority>
+  </url>`;
+  }).join('\n');
+
+  const llmsSitemapXml = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urlEntries}
+</urlset>`;
+
+  siteCatalog.addFile({
+    contents: Buffer.from(llmsSitemapXml, 'utf8'),
+    out: { path: 'sitemap-llms.xml' },
+  });
+  logger.info(`Created sitemap-llms.xml with ${llmsFiles.length} entries`);
+
+  // Find and update the main sitemap index
+  const sitemapIndex = siteCatalog.getFiles().find(file =>
+    file.out.path === 'sitemap.xml'
+  );
+
+  if (!sitemapIndex) {
+    logger.warn('Main sitemap.xml not found, cannot add llms sitemap to index');
+    return;
+  }
+
+  // Parse and update the sitemap index
+  let sitemapIndexXml = sitemapIndex.contents.toString('utf8');
+
+  // Add lastmod to all existing component sitemaps for consistency
+  sitemapIndexXml = addLastmodToComponentSitemaps(contentCatalog, siteCatalog, sitemapIndexXml, siteUrl, logger);
+
+  // Check if sitemap-llms.xml is already in the index
+  if (sitemapIndexXml.includes('sitemap-llms.xml')) {
+    logger.debug('sitemap-llms.xml already in sitemap index');
+    // Update the index with modified component sitemaps even if llms sitemap exists
+    sitemapIndex.contents = Buffer.from(sitemapIndexXml, 'utf8');
+    return;
+  }
+
+  // Find the most recent date from all llms files for the sitemap-llms.xml lastmod
+  let sitemapLastmod = now;
+  if (gitDates.size > 0) {
+    const dates = Array.from(gitDates.values()).map(d => new Date(d));
+    const mostRecent = new Date(Math.max(...dates));
+    sitemapLastmod = mostRecent.toISOString();
+  }
+
+  // Add sitemap-llms.xml entry before the closing </sitemapindex> tag
+  const llmsSitemapEntry = `  <sitemap>
+    <loc>${siteUrl}/sitemap-llms.xml</loc>
+    <lastmod>${sitemapLastmod}</lastmod>
+  </sitemap>
+</sitemapindex>`;
+
+  sitemapIndexXml = sitemapIndexXml.replace('</sitemapindex>', llmsSitemapEntry);
+
+  // Update the sitemap index in the catalog
+  sitemapIndex.contents = Buffer.from(sitemapIndexXml, 'utf8');
+  logger.info('Added sitemap-llms.xml to main sitemap index');
+}
+
+/**
+ * Add lastmod to all component sitemaps in the sitemap index for consistency
+ * Also updates the component sitemaps themselves to use git dates instead of build time
+ *
+ * @param {Object} contentCatalog - Antora content catalog (source pages with git dates)
+ * @param {Object} siteCatalog - Antora site catalog (output files including sitemaps)
+ * @param {string} sitemapIndexXml - The sitemap index XML content
+ * @param {string} siteUrl - Base site URL for matching URLs
+ * @param {Object} logger - Logger instance
+ */
+function addLastmodToComponentSitemaps(contentCatalog, siteCatalog, sitemapIndexXml, siteUrl, logger) {
+  // Build a map of URL -> git date from all pages
+  const urlToGitDate = new Map();
+  const allPages = contentCatalog.getPages();
+
+  allPages.forEach(page => {
+    if (page.pub?.url && page.asciidoc?.attributes?.['page-git-modified-date']) {
+      const gitDate = page.asciidoc.attributes['page-git-modified-date'];
+      const url = `${siteUrl}${page.pub.url}`;
+      urlToGitDate.set(url, gitDate);
+    }
+  });
+
+  logger.info(`Built URL -> git date map with ${urlToGitDate.size} entries`);
+  if (urlToGitDate.size > 0 && urlToGitDate.size < 20) {
+    urlToGitDate.forEach((date, url) => {
+      logger.debug(`  ${url} -> ${date}`);
+    });
+  }
+
+  // Find all component sitemap XML files
+  const componentSitemaps = siteCatalog.getFiles()
+    .filter(file => {
+      const path = file.out.path;
+      return path.startsWith('sitemap-') &&
+             path.endsWith('.xml') &&
+             path !== 'sitemap-llms.xml';
+    });
+
+  logger.debug(`Found ${componentSitemaps.length} component sitemaps to update with git dates`);
+
+  // For each component sitemap, update URLs with git dates and find the most recent
+  componentSitemaps.forEach(sitemapFile => {
+    const filename = sitemapFile.out.path;
+    let xml = sitemapFile.contents.toString('utf8');
+    const dates = [];
+    let updatedCount = 0;
+
+    // Update each URL in the sitemap with its git date if available
+    xml = xml.replace(
+      /<url>\s*<loc>([^<]+)<\/loc>\s*<lastmod>([^<]+)<\/lastmod>\s*<\/url>/g,
+      (match, url, oldDate) => {
+        const gitDate = urlToGitDate.get(url);
+        if (gitDate) {
+          updatedCount++;
+          dates.push(new Date(gitDate));
+          return `<url>\n<loc>${url}</loc>\n<lastmod>${gitDate}</lastmod>\n</url>`;
+        } else {
+          // Keep original date
+          try {
+            dates.push(new Date(oldDate));
+          } catch (e) {
+            // Skip invalid dates
+          }
+          return match;
+        }
+      }
+    );
+
+    // Update the sitemap file in the catalog
+    sitemapFile.contents = Buffer.from(xml, 'utf8');
+    logger.info(`Updated sitemap ${filename}: ${updatedCount} URLs with git dates, ${dates.length} total dates`);
+
+    if (dates.length === 0) {
+      logger.debug(`No dates found in ${filename}`);
+      return;
+    }
+
+    // Find the most recent date
+    const mostRecent = new Date(Math.max(...dates));
+    const lastmod = mostRecent.toISOString();
+
+    // Update the sitemap index entry to include/update lastmod
+    // Match various patterns since Antora might have different formatting
+    const locPattern = new RegExp(
+      `(<loc>[^<]*/${filename.replace(/\./g, '\\.')}</loc>)(?:\\s*<lastmod>[^<]*</lastmod>)?\\s*</sitemap>`,
+      'g'
+    );
+
+    sitemapIndexXml = sitemapIndexXml.replace(
+      locPattern,
+      `$1\n    <lastmod>${lastmod}</lastmod>\n  </sitemap>`
+    );
+
+    logger.debug(`Updated lastmod to ${lastmod} for ${filename} in index`);
+  });
+
+  return sitemapIndexXml;
+}