“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 documenteer_last_modified_date_format 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).

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 property used by social-media link previews.

  • <meta name="dcterms.modified"> — the Dublin Core modification date.

  • A Schema.org 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 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, set fetch-depth: 0:

.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 conf.py and render the last_updated context value. With pydata-sphinx-theme, add the last-updated component to the article footer:

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 conf.py file.

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 show_last_updated field in documenteer.toml.

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.

conf.py#
documenteer_last_modified_date_format = "%Y-%m-%d"

This page was last modified on .