Feature request: per-page lastmod from source metadata (git history / frontmatter)

[mderazon]

Feature Request: Per-page lastmod from source file metadata (git history / frontmatter)

Current Behavior

@astrojs/sitemap supports a top-level lastmod option that stamps every page with the same date:

sitemap({ lastmod: new Date() })

This is misleading for sites where only a subset of pages changes per build, because search engines receive inaccurate signals about which content is fresh.

The serialize() escape hatch allows per-page customization, but users must manually reverse-map every item.url back to its source file and run their own git log / fs.stat logic. This is boilerplate-heavy and error-prone, especially for content-heavy sites with hundreds of pages and nested content collections.

Use Case

We run a documentation site (Starlight + @astrojs/sitemap) with ~700 pages. Only a few articles change per deployment, but the current setup forces us to either:

• Omit lastmod entirely (loses crawl-priority signals for updated pages)
• Stamp every page with the build time (causes search engines to re-crawl unchanged pages)

We want each <url> entry to carry the actual last modification date of its source file.

Prior Art

Starlight already solves the same problem for page footers via lastUpdated:

• It runs a bulk git log query to get the newest commit date per file.
• It supports a lastUpdated frontmatter field for manual override.
• It gracefully falls back when git history is unavailable (shallow clones).

However, this computed date is not exposed to @astrojs/sitemap or any other integration, so it cannot be reused for the sitemap.

Proposed Solutions

Option A — lastmodSource callback in @astrojs/sitemap

Allow users to provide a function that maps each page URL to its lastmod value before serialize() is called:

sitemap({
  lastmodSource: (url) => {
    // User maps URL back to source file, reads git date, returns ISO string or undefined
    const filePath = mapUrlToSourceFile(url);
    return getGitCommitDate(filePath);
  }
})

This keeps the integration framework-agnostic while removing the need for boilerplate serialize() code.

Option B — Astro integration API: expose source file path in astro:build:done

If the pages array in astro:build:done included a reference to the source file path (e.g., src/content/docs/foo.mdx), @astrojs/sitemap could optionally derive lastmod automatically from git history or file mtime. This would benefit any integration that needs source metadata, not just sitemaps.

Option C — Re-use frontmatter / content collection metadata

If @astrojs/sitemap could access the parsed frontmatter of each page (or the content collection entry), users could set a lastmod / lastUpdated field in frontmatter and the integration could pick it up automatically—similar to how RSS feeds consume frontmatter dates.

Environment

• @astrojs/sitemap: 3.x
• Astro: 6.x
• Use case: Starlight documentation site with ~700 pages, deployed via CI (GitHub Actions)

Additional Context

• Google officially ignores changefreq and priority, but still uses lastmod for crawl scheduling.
• Community workarounds exist (custom serialize() + child_process.execSync('git log')), but they add maintenance burden and are slow when done per-page instead of in bulk.
• Related: Starlight issue #2084 (shallow clone behavior), Starlight PR #256 (lastUpdated feature).

---

Also filed as issue #16803 on the main repo.

[florian-lefebvre]

You can do achieve this by using https://inox-tools.fryuni.dev/sitemap-ext and custom integrations, but I agree it is not ideal