documenteer 2.3.0__tar.gz → 2.4.0__tar.gz

{documenteer-2.3.0 → documenteer-2.4.0}/.github/workflows/ci-cron.yaml

@@ -16,14 +16,14 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           cache: 'npm'
           node-version-file: '.nvmrc'
@@ -71,11 +71,11 @@ jobs:
           - "dev"
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version-file: '.nvmrc'
 
@@ -115,11 +115,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           cache: 'npm'
           node-version-file: '.nvmrc'
@@ -160,11 +160,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version-file: '.nvmrc'
 

{documenteer-2.3.0 → documenteer-2.4.0}/.github/workflows/ci.yaml

@@ -22,14 +22,14 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           cache: 'npm'
           node-version-file: '.nvmrc'
@@ -65,11 +65,11 @@ jobs:
           - '8'
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           cache: 'npm'
           node-version-file: '.nvmrc'
@@ -99,14 +99,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
       - name: Setup Graphviz
         uses: ts-graphviz/setup-graphviz@v2
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           cache: 'npm'
           node-version-file: '.nvmrc'
@@ -148,11 +148,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           cache: 'npm'
           node-version-file: '.nvmrc'
@@ -185,11 +185,11 @@ jobs:
     if: github.event_name == 'release' && github.event.action == 'published'
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           cache: 'npm'
           node-version-file: '.nvmrc'

{documenteer-2.3.0 → documenteer-2.4.0}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-2.4.0'></a>
+## 2.4.0 (2026-06-17)
+
+### New features
+
+- User guide pages now show a "This page was last modified on <date>." timestamp at the bottom of each page, derived from the page's Git commit history. The date is the most recent commit across the page's own source file and any files it pulls in via `include`/`literalinclude`, so editing an included snippet updates every page that uses it. This is on by default and can be disabled with `show_last_updated = false` in the `[sphinx.theme]` table of `documenteer.toml`.
+
+  The footer date is rendered as a `<time>` element whose `datetime` attribute carries the canonical UTC ISO 8601 timestamp, and a small bundled script (`rubin-last-modified.js`) rewrites the visible text to the reader's own local date (for example "June 1, 2024"). With JavaScript disabled the element falls back to the UTC date as `YYYY-MM-DD`. This ensures readers in any timezone see the correct calendar day, which a fixed UTC date can otherwise misrepresent.
+
+  The extension is also the single source of truth for the page's last-modified date in the HTML `<head>`: it emits the same Git date as an `article:modified_time` (Open Graph), `dcterms.modified` (Dublin Core), and a Schema.org `dateModified` (JSON-LD). The user-guide preset sets `git_last_updated_metatags = false` so the auto-loaded `sphinx-last-updated-by-git` extension (still used for the sitemap) doesn't emit a duplicate Open Graph tag from a separate Git computation.
+
+  Because the date comes from Git, CI builds must check out the full history (set `fetch-depth: 0` with `actions/checkout`). To avoid publishing misleading dates, Documenteer detects a shallow clone, omits the timestamp from every page, and emits a build warning.
+
+### Other changes
+
+- Fixed pytest configuration in `pyproject.toml` by consolidating conflicting `[tool.pytest]` and `[tool.pytest.ini_options]` sections into a single `[tool.pytest.ini_options]` section. This resolves an error that prevented tests from running.
+
 <a id='changelog-2.3.0'></a>
 ## 2.3.0 (2025-09-03)
 

{documenteer-2.3.0 → documenteer-2.4.0}/Makefile

@@ -9,7 +9,7 @@ help:
 init:
 	rm -rf .tox
 	uv pip install --upgrade pre-commit tox tox-uv scriv
-	uv pip install -e ".[technote,pipelines]" --group dev
+	uv pip install -e ".[technote,guide]" --group dev
 	pre-commit install
 
 .PHONY: clean

{documenteer-2.3.0/src/documenteer.egg-info → documenteer-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documenteer
-Version: 2.3.0
+Version: 2.4.0
 Summary: Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations.
 License-Expression: MIT
 Project-URL: Homepage, https://documenteer.lsst.io

{documenteer-2.3.0 → documenteer-2.4.0}/docs/changelog.md

@@ -2,6 +2,23 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-2.4.0'></a>
+## 2.4.0 (2026-06-17)
+
+### New features
+
+- User guide pages now show a "This page was last modified on <date>." timestamp at the bottom of each page, derived from the page's Git commit history. The date is the most recent commit across the page's own source file and any files it pulls in via `include`/`literalinclude`, so editing an included snippet updates every page that uses it. This is on by default and can be disabled with `show_last_updated = false` in the `[sphinx.theme]` table of `documenteer.toml`.
+
+  The footer date is rendered as a `<time>` element whose `datetime` attribute carries the canonical UTC ISO 8601 timestamp, and a small bundled script (`rubin-last-modified.js`) rewrites the visible text to the reader's own local date (for example "June 1, 2024"). With JavaScript disabled the element falls back to the UTC date as `YYYY-MM-DD`. This ensures readers in any timezone see the correct calendar day, which a fixed UTC date can otherwise misrepresent.
+
+  The extension is also the single source of truth for the page's last-modified date in the HTML `<head>`: it emits the same Git date as an `article:modified_time` (Open Graph), `dcterms.modified` (Dublin Core), and a Schema.org `dateModified` (JSON-LD). The user-guide preset sets `git_last_updated_metatags = false` so the auto-loaded `sphinx-last-updated-by-git` extension (still used for the sitemap) doesn't emit a duplicate Open Graph tag from a separate Git computation.
+
+  Because the date comes from Git, CI builds must check out the full history (set `fetch-depth: 0` with `actions/checkout`). To avoid publishing misleading dates, Documenteer detects a shallow clone, omits the timestamp from every page, and emits a build warning.
+
+### Other changes
+
+- Fixed pytest configuration in `pyproject.toml` by consolidating conflicting `[tool.pytest]` and `[tool.pytest.ini_options]` sections into a single `[tool.pytest.ini_options]` section. This resolves an error that prevented tests from running.
+
 <a id='changelog-2.3.0'></a>
 ## 2.3.0 (2025-09-03)
 

{documenteer-2.3.0 → documenteer-2.4.0}/docs/dev/api/documenteer.ext.rst

@@ -11,6 +11,9 @@ documenteer.ext
 .. automodapi:: documenteer.ext.jira
    :no-inheritance-diagram:
 
+.. automodapi:: documenteer.ext.lastmodified
+   :no-inheritance-diagram:
+
 .. automodapi:: documenteer.ext.lsstdocushare
    :no-inheritance-diagram:
 

{documenteer-2.3.0 → documenteer-2.4.0}/docs/documenteer.toml

@@ -45,7 +45,11 @@ technote = "https://technote.lsst.io/"
 [sphinx.linkcheck]
 ignore = [
     "https://mermaid-js.github.io",
-    "https://rubin-obs.slack.com"
+    "https://rubin-obs.slack.com",
+    "https://slack.com/app_redirect",
+    # github.dev redirects to the vscode.dev SPA, which doesn't finish
+    # loading within linkcheck's timeout and reports a false-positive timeout.
+    "https://github.dev",
 ]
 
 [sphinx.redirects]

{documenteer-2.3.0 → documenteer-2.4.0}/docs/guides/toml-reference.rst

@@ -426,6 +426,47 @@ This configuration requires information about the GitHub repository from these o
 - :ref:`project.github_url <guide-project-github-url>`
 - :ref:`project.github_default_branch <guide-project-github-default-branch>`
 
+.. _guide-project-show-last-updated:
+
+show_last_updated
+-----------------
+
+|optional|
+
+Default is ``true``, so that each page shows a "Last updated on <date>." timestamp at the bottom of each page.
+
+.. seealso::
+
+   :doc:`/sphinx-extensions/last-updated` for how the date is computed and the extension's
+   Sphinx configuration values.
+
+The date is computed from the page's **Git commit history**, not the filesystem modification time (which is meaningless in CI).
+It is the most recent commit date across the page's own source file *and* any files the page pulls in with ``include`` or ``literalinclude`` directives, so editing an included snippet updates every page that uses it.
+Because the date is the last *commit* date, uncommitted local edits don't change it; a page whose source has never been committed shows no timestamp.
+
+Set this to ``false`` to hide the timestamp:
+
+.. code-block:: toml
+   :caption: documenteer.toml
+
+   [sphinx.theme]
+   show_last_updated = false
+
+.. important::
+
+   Because the date comes from the Git history, your CI build must check out the **full** commit history.
+   With `actions/checkout <https://github.com/actions/checkout>`__, set ``fetch-depth: 0``:
+
+   .. code-block:: yaml
+      :caption: .github/workflows/ci.yaml
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+   A shallow clone (the default) only fetches the most recent commit, so every page would otherwise report the same, incorrect date.
+   To avoid publishing misleading data, Documenteer detects a shallow clone, **omits the "Last updated" timestamp from every page**, and emits a single build warning telling you to set ``fetch-depth: 0``.
+
 [sphinx.intersphinx]
 ====================
 

{documenteer-2.3.0 → documenteer-2.4.0}/docs/sphinx-extensions/index.rst

@@ -19,3 +19,10 @@ Sphinx extensions
 
    remote-code-block
    openapi
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :caption: Page metadata
+
+   last-updated

documenteer-2.4.0/docs/sphinx-extensions/last-updated.rst

@@ -0,0 +1,137 @@
+.. _documenteer-ext-lastmodified:
+
+##############################
+"Last updated" page timestamps
+##############################
+
+Documenteer's ``documenteer.ext.lastmodified`` extension adds a "This page was last modified on <date>." timestamp to the bottom of each page's article body.
+The date is derived from the page's **Git commit history** rather than the filesystem modification time, which is meaningless in CI where checkouts have arbitrary timestamps.
+In the user-guide preset the footer date is rendered to the **reader's** local timezone (see `Reader-localized footer date`_).
+It is also the single source of truth for the page's last-modified date in the HTML ``<head>``, where it emits the same Git date as Open Graph, Dublin Core, and Schema.org metadata (see `HTML metadata`_).
+
+The extension exposes the date to the page template in three forms:
+
+- ``last_updated`` — the date formatted with :ref:`documenteer_last_modified_date_format <documenteer-last-modified-date-format-conf>` in the commit's own timezone offset. Sphinx emits this as the ``docbuild:last-update`` meta tag, and it is the value any theme-agnostic ``last-updated`` rendering uses.
+- ``documenteer_last_modified_iso`` — the canonical UTC ISO 8601 timestamp (for example ``2024-06-01T00:00:00+00:00``).
+- ``documenteer_last_modified_date`` — the UTC date as ``YYYY-MM-DD`` (for example ``2024-06-01``).
+
+Reader-localized footer date
+============================
+
+In the user-guide preset, Documenteer overrides pydata-sphinx-theme's ``last-updated`` component to render the footer date as a ``<time>`` element:
+
+.. code-block:: html
+
+   <time datetime="2024-06-01T00:00:00+00:00">2024-06-01</time>
+
+The ``datetime`` attribute carries the canonical UTC ISO 8601 timestamp, and the visible text is the UTC date as ``YYYY-MM-DD``.
+A small bundled script (``rubin-last-modified.js``) then rewrites the visible text to the **reader's** local date in a long-month style, for example "June 1, 2024".
+This matters because a UTC date can fall on a different calendar day than the reader's local date; localizing in the browser shows each reader the correct day.
+With JavaScript disabled the element keeps its ``YYYY-MM-DD`` UTC fallback text.
+
+.. tip::
+
+   If you use Documenteer's user-guide configuration preset, this extension is already enabled and the timestamp is shown by default.
+   Toggle it with the :ref:`show_last_updated <guide-project-show-last-updated>` setting in :file:`documenteer.toml`; you don't need to edit :file:`conf.py`.
+
+How the date is computed
+========================
+
+The timestamp is the most recent commit date across the page's own source file *and* any files it pulls in with the ``include`` or ``literalinclude`` directives.
+Editing an included snippet therefore updates the timestamp on every page that uses it.
+
+Because the date is the last *commit* date:
+
+- Uncommitted local edits don't change it.
+- A page whose source has never been committed shows no timestamp.
+- Generated pages without a source document (such as the search page and general index) show no timestamp.
+
+HTML metadata
+=============
+
+Besides the visible footer timestamp, the extension writes the **same Git commit date** into the page's HTML ``<head>`` as three machine-readable signals, so that downstream consumers all agree:
+
+- ``<meta property="article:modified_time">`` — the `Open Graph <https://ogp.me/>`__ property used by social-media link previews.
+- ``<meta name="dcterms.modified">`` — the `Dublin Core <https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#modified>`__ modification date.
+- A `Schema.org <https://schema.org/dateModified>`__ ``dateModified`` field inside a JSON-LD ``<script type="application/ld+json">`` block (typed as ``WebPage``).
+
+These three head signals are expressed in **UTC** (ISO 8601, ``+00:00``), so the metadata is identical regardless of the committer's timezone — a locally-authored commit and its UTC-recorded squash-merge produce the same value.
+The visible footer date, by contrast, reflects the commit's own offset.
+
+In addition, pydata-sphinx-theme renders a ``<meta name="docbuild:last-update">`` tag from the same ``last_updated`` context value.
+
+.. note::
+
+   sphinx-sitemap (enabled by the user-guide preset) auto-loads `sphinx-last-updated-by-git <https://github.com/mgeier/sphinx-last-updated-by-git>`__ to populate the sitemap's ``<lastmod>`` entries.
+   That extension runs its *own* Git computation and would otherwise emit a second, potentially divergent ``article:modified_time`` tag.
+   To keep this extension the single source of truth, the user-guide preset sets ``git_last_updated_metatags = False``, which silences the duplicate Open Graph tag while leaving the sitemap behavior intact.
+
+Full Git history is required
+============================
+
+The date comes from Git, so the build must have the **full** commit history.
+
+.. important::
+
+   With `actions/checkout <https://github.com/actions/checkout>`__, set ``fetch-depth: 0``:
+
+   .. code-block:: yaml
+      :caption: .github/workflows/ci.yaml
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+   A shallow clone (the default) only fetches the most recent commit, so every page would otherwise report the same, incorrect date.
+   To avoid publishing misleading data, Documenteer detects a shallow clone, omits the timestamp from every page, and emits a single build warning.
+
+Reference
+=========
+
+Extension module
+----------------
+
+The user-guide configuration preset enables this extension automatically.
+To use it in a standalone Sphinx project, add ``"documenteer.ext.lastmodified"`` to the extensions list in :file:`conf.py` and render the ``last_updated`` context value.
+With pydata-sphinx-theme, add the ``last-updated`` component to the article footer:
+
+.. code-block:: python
+   :caption: conf.py
+
+   extensions = ["documenteer.ext.lastmodified", ...]
+
+   html_theme = "pydata_sphinx_theme"
+   html_theme_options = {
+       "article_footer_items": ["last-updated"],
+   }
+
+Configurations
+--------------
+
+Set these configurations in the Sphinx :file:`conf.py` file.
+
+.. _documenteer-last-modified-enabled-conf:
+
+documenteer\_last\_modified\_enabled
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Whether to compute and show the "Last updated" timestamp.
+A boolean that defaults to `True`.
+In the user-guide preset this is set automatically from the :ref:`show_last_updated <guide-project-show-last-updated>` field in :file:`documenteer.toml`.
+
+.. _documenteer-last-modified-date-format-conf:
+
+documenteer\_last\_modified\_date\_format
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``strftime``-style format string for the ``last_updated`` value.
+Defaults to ``"%b %d, %Y"`` (for example, ``Jun 16, 2026``).
+The date is formatted with Sphinx's date machinery, so it respects the build's ``language`` setting.
+
+This format governs the ``last_updated`` context value — the ``docbuild:last-update`` meta tag and any theme-agnostic ``last-updated`` rendering — **not** the visible footer date in the user-guide preset.
+That footer date is rendered from the UTC ISO timestamp and localized to the reader's timezone by JavaScript (see `Reader-localized footer date`_), so it is not affected by this setting.
+
+.. code-block:: python
+   :caption: conf.py
+
+   documenteer_last_modified_date_format = "%Y-%m-%d"

{documenteer-2.3.0 → documenteer-2.4.0}/pyproject.toml

@@ -163,10 +163,8 @@ exclude_lines = [
     "if TYPE_CHECKING:",
 ]
 
-[tool.pytest]
-norecursedirs = "node_modules"
-
 [tool.pytest.ini_options]
+norecursedirs = "node_modules"
 python_files = ["tests/*.py", "tests/*/*.py"]
 
 [tool.mypy]

documenteer-2.4.0/src/documenteer/assets/rubin-last-modified.js

@@ -0,0 +1,45 @@
+// Localize documenteer.ext.lastmodified's "last modified" footer date.
+//
+// The footer renders the page's Git commit date as a <time> element whose
+// datetime attribute carries the canonical UTC ISO 8601 timestamp and whose
+// visible text is the UTC date (YYYY-MM-DD) as a no-JavaScript fallback. This
+// script rewrites that text to the reader's own local date in a long-month
+// style (for example "June 1, 2024"), so a UTC date that lands on a different
+// calendar day than the reader's is shown correctly for the reader.
+//
+// On any parse failure or invalid date the UTC fallback text is left intact.
+(function () {
+  'use strict';
+
+  function localize() {
+    var elements = document.querySelectorAll(
+      'time[data-documenteer-last-modified]'
+    );
+    for (var i = 0; i < elements.length; i++) {
+      var element = elements[i];
+      var iso = element.getAttribute('datetime');
+      if (!iso) {
+        continue;
+      }
+      try {
+        var date = new Date(iso);
+        if (isNaN(date.getTime())) {
+          continue;
+        }
+        element.textContent = date.toLocaleDateString(undefined, {
+          year: 'numeric',
+          month: 'long',
+          day: 'numeric',
+        });
+      } catch (error) {
+        // Leave the UTC fallback text untouched.
+      }
+    }
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', localize);
+  } else {
+    localize();
+  }
+})();

{documenteer-2.3.0 → documenteer-2.4.0}/src/documenteer/assets/rubin-pydata-theme.css

@@ -109,3 +109,25 @@ body {
 .navbar-nav i {
   font-size: var(--pst-font-size-icon);
 }
+
+/* "Last updated" timestamp at the bottom of the article body
+ * (documenteer.ext.lastmodified -> pydata "last-updated" component).
+ * Left-aligned, muted, with breathing room above and below so it reads as
+ * page metadata between the body and the prev/next navigation. */
+.bd-footer-article .last-updated {
+  margin-top: 1.5rem;
+  margin-bottom: 0.5rem;
+  text-align: left;
+  font-size: 0.875em;
+  color: var(--pst-color-text-muted);
+}
+
+/* Indent the footer so the timestamp lines up with the article body text.
+ * pydata-sphinx-theme only indents the article (.bd-article) by 2rem at
+ * >=1200px, so match that breakpoint to avoid over-indenting on narrow
+ * screens, where the body has no extra indent. */
+@media (min-width: 1200px) {
+  .bd-footer-article {
+    padding-left: 2rem;
+  }
+}

{documenteer-2.3.0 → documenteer-2.4.0}/src/documenteer/conf/_toml.py

@@ -198,6 +198,14 @@ class ThemeModel(BaseModel):
         ),
     )
 
+    show_last_updated: bool = Field(
+        True,
+        description=(
+            "Show a 'Last updated' timestamp at the bottom of each page "
+            "derived from Git commit dates if True"
+        ),
+    )
+
 
 class SphinxModel(BaseModel):
     """Model for Sphinx configurations in documenteer.toml."""
@@ -565,3 +573,13 @@ class DocumenteerConfig:
             return self.conf.sphinx.theme.header_links_before_dropdown
         else:
             return 5
+
+    @property
+    def show_last_updated(self) -> bool:
+        """Whether to show a "Last updated" timestamp at the bottom of each
+        page derived from Git commit dates.
+        """
+        if self.conf.sphinx:
+            return self.conf.sphinx.theme.show_last_updated
+        else:
+            return True

{documenteer-2.3.0 → documenteer-2.4.0}/src/documenteer/conf/_utils.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
+from datetime import datetime
 from pathlib import Path
 
 from git import Repo
@@ -107,6 +109,10 @@ class GitRepository:
 
     def __init__(self, dirname: Path) -> None:
         self._repo = Repo(dirname, search_parent_directories=True)
+        # Cache of the last-modified datetime for each absolute path so that
+        # shared dependencies (e.g. included files) are only resolved once per
+        # build, rather than once per referencing page.
+        self._last_modified_cache: dict[str, datetime | None] = {}
 
     @property
     def working_tree_dir(self) -> Path:
@@ -116,6 +122,70 @@ class GitRepository:
             raise RuntimeError("Git repository is not available.")
         return Path(path)
 
+    @property
+    def is_shallow(self) -> bool:
+        """Whether the repository is a shallow clone.
+
+        A shallow clone (such as one produced by ``actions/checkout`` without
+        ``fetch-depth: 0``) does not contain the full commit history, so
+        commit-date lookups are unreliable.
+        """
+        result = self._repo.git.rev_parse("--is-shallow-repository")
+        return result.strip() == "true"
+
+    def compute_last_modified(
+        self, paths: Sequence[Path | str]
+    ) -> datetime | None:
+        """Compute the most-recent commit datetime across a set of paths.
+
+        Parameters
+        ----------
+        paths
+            Paths to consider. Typically a page's source file together with
+            any files it pulls in via ``include``/``literalinclude``.
+
+        Returns
+        -------
+        datetime.datetime or None
+            The most recent commit datetime (timezone-aware) across all of the
+            tracked ``paths``. Paths that are untracked (e.g. new or
+            uncommitted files), or that lie outside the Git working tree, are
+            ignored. Returns `None` if none of the paths are tracked in the
+            repository.
+        """
+        working_tree_dir = self.working_tree_dir.resolve()
+        datetimes: list[datetime] = []
+        for path in paths:
+            abs_path = Path(path).resolve()
+
+            # Defensively skip paths that aren't inside the working tree; Git
+            # cannot report history for them.
+            if not abs_path.is_relative_to(working_tree_dir):
+                continue
+
+            key = str(abs_path)
+            if key in self._last_modified_cache:
+                cached = self._last_modified_cache[key]
+            else:
+                cached = self._get_path_last_modified(abs_path)
+                self._last_modified_cache[key] = cached
+
+            if cached is not None:
+                datetimes.append(cached)
+
+        if not datetimes:
+            return None
+        return max(datetimes)
+
+    def _get_path_last_modified(self, path: Path) -> datetime | None:
+        """Get the datetime of the most recent commit touching a single path,
+        or `None` if the path isn't tracked.
+        """
+        commits = list(self._repo.iter_commits(paths=str(path), max_count=1))
+        if not commits:
+            return None
+        return commits[0].committed_datetime
+
 
 def extend_excludes_for_non_index_source(
     exclude_patterns: list[str],