Registry / devops / mkdocs-git-revision-date-plugin

mkdocs-git-revision-date-plugin

library0.3.2pypypiunverified

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.

devops

pip install mkdocs-git-revision-date-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · MKDOCS-GIT-REVISIO

mkdocs-git-revision-date-plugin

devopspythonv0.3.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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 %}

Debug

Known issues

gotchaThis 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`.

affects: All versions

breakingIn 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`.

affects: All versions

breakingUpcoming 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.

affects: Future MkDocs 2.0

gotchaIf 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`.

affects: All versions

Errors

Common errors & fixes

ERROR - [git-revision-date-plugin] Unable to find a git directory and/or git is not installed. To ignore this error, set option 'fallback_to_build_date: true'

The plugin requires the 'git' command-line tool to be installed and accessible in the system's PATH, and the MkDocs project must be initialized as a Git repository.

fix

Ensure Git is installed and added to your system's PATH. Confirm your MkDocs project directory is a Git repository (run `git init` and commit some files if not). For CI/CD environments, ensure a full Git history is fetched (e.g., `actions/checkout@v4 with: fetch-depth: 0` for GitHub Actions).

ERROR - Config value 'plugins': Invalid Plugins configuration Aborted with 1 Configuration Errors!

The 'mkdocs.yml' configuration file has an incorrect YAML structure under the 'plugins' section, or the plugin name 'git-revision-date' is misspelled or improperly indented.

fix

Correct the YAML indentation and ensure the plugin is listed correctly at the top level of your `mkdocs.yml` file. Remember to include other default plugins like 'search' if you previously relied on MkDocs enabling them automatically. 

```yaml
plugins:
  - search
  - git-revision-date
```

{{ git_revision_date }} (appears as plain text in the generated HTML)

The plugin is not correctly activated in `mkdocs.yml`, or the Jinja2 templating for `{{ git_revision_date }}` in Markdown files is not being processed, or the custom theme does not properly display the `page.meta.revision_date` variable.

fix

First, ensure the plugin is correctly configured in `mkdocs.yml` (see previous fix). If using in a Markdown file, `{{ git_revision_date }}` should render automatically. If using in a custom theme template, integrate `{{ page.meta.revision_date }}` within your theme's HTML files (e.g., `main.html` or a partial) using Jinja2 syntax like:

```jinja2
{% if page.meta.revision_date %}
    <small>Last updated: {{ page.meta.revision_date }}</small>
{% endif %}
```

Upgrade

Version history

0.3.2latest on PyPI · released Mar 8, 2022

Audit

Dependencies

mkdocsrequiredCore dependency for any MkDocs plugin.

GitPythonrequiredRequired for interacting with Git to retrieve revision dates.

Agent activity

4 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/zhaoterryy/mkdocs-git-revision-date-plugin ↗

packagehttps://pypi.org/project/mkdocs-git-revision-date-plugin/ ↗