MkDocs Git Revision Date Plugin

0.3.2 · active · verified Mon Apr 13

mkdocs-git-revision-date-plugin is an MkDocs plugin that automatically retrieves and displays the last Git revision date for each Markdown page in an MkDocs site. It provides the revision date in ISO (YYYY-mm-dd) format for use in page templates or directly within Markdown files. As of version 0.3.2, it is considered to be in maintenance mode, with more feature-rich development continuing in the `mkdocs-git-revision-date-localized-plugin` fork.

Warnings

gotcha This plugin provides only ISO formatted dates (YYYY-mm-dd) and lacks localization features. For more advanced date formatting, localization, or to display page creation dates, it is highly recommended to use the `mkdocs-git-revision-date-localized-plugin` fork, which is more actively maintained and feature-rich.
Fix: Consider migrating to `mkdocs-git-revision-date-localized-plugin` for enhanced functionality. Install it with `pip install mkdocs-git-revision-date-localized-plugin` and update your `mkdocs.yml` to `plugins: - git-revision-date-localized`.
breaking In CI/CD environments (e.g., GitHub Actions, GitLab CI), Git repositories often perform shallow clones by default. To correctly retrieve historical revision dates for all files, you must configure your CI/CD pipeline to fetch the full Git history (e.g., set `fetch-depth: 0` for GitHub Actions or `GIT_DEPTH: 0` for GitLab CI).
Fix: Adjust your CI/CD workflow to ensure a full Git history clone. Example for GitHub Actions: `actions/checkout@v4 with: fetch-depth: 0`.
breaking Upcoming versions of MkDocs (specifically MkDocs 2.0) are anticipated to introduce significant backward-incompatible changes. The plugin system is expected to be removed, meaning this plugin (and all other MkDocs plugins) will likely cease to function with MkDocs 2.0.
Fix: Monitor official MkDocs documentation and the Material for MkDocs blog for migration strategies and potential alternatives when MkDocs 2.0 is released. You may need to pin your `mkdocs` dependency to `<2` to avoid automatic upgrades.
gotcha If you define any plugins in your `mkdocs.yml` (including `git-revision-date`), MkDocs' default `search` plugin is no longer automatically enabled. You must explicitly add `search` to your `plugins` list if you want to retain search functionality.
Fix: Ensure your `plugins` section in `mkdocs.yml` includes `search`, e.g., `plugins: - search - git-revision-date`.

Install

pip install mkdocs-git-revision-date-plugin Install with pip

Quickstart

Add the plugin to your `mkdocs.yml` file under the `plugins` section. The revision date can then be accessed in Markdown files using the `{{ git_revision_date }}` Jinja2 variable, or in theme templates via `page.meta.revision_date`. Remember to include the `search` plugin explicitly if you define any plugins.

plugins:
  - search
  - git-revision-date

# Example usage in a Markdown file:
# Page last revised on: {{ git_revision_date }}

# Example usage in an MkDocs template (e.g., in a custom theme):
# {% if page.meta.revision_date %}
# <small>Last updated {{ page.meta.revision_date }}</small>
# {% endif %}

view raw JSON →