tessl/pypi-mkdocs-git-revision-date-localized-plugin

MkDocs plugin that enables displaying the localized date of the last git modification of a markdown file.

—

Pending

Overview

Eval results

Files

Template Variables & Tags

Name: tessl/pypi-mkdocs-git-revision-date-localized-plugin
Author: tessl

Template integration providing access to git revision information through page metadata variables and markdown template tags. The plugin automatically adds comprehensive revision date information to every page's metadata and processes template tags in markdown content.

Capabilities

Page Metadata Variables

Automatically added variables accessible through page.meta in templates and themes.

# Last revision date information
page.meta['git_revision_date_localized']          # Formatted last revision date
page.meta['git_revision_date_localized_hash']     # Commit hash of last revision
page.meta['git_revision_date_localized_tag']      # Git tag for last revision (if any)

# Raw date formats for last revision (without HTML spans)
page.meta['git_revision_date_localized_raw_date']        # Raw date format
page.meta['git_revision_date_localized_raw_datetime']    # Raw datetime format
page.meta['git_revision_date_localized_raw_iso_date']    # Raw ISO date format
page.meta['git_revision_date_localized_raw_iso_datetime'] # Raw ISO datetime format
page.meta['git_revision_date_localized_raw_timeago']     # Raw timeago format
page.meta['git_revision_date_localized_raw_custom']      # Raw custom format

# Site-wide last revision information
page.meta['git_site_revision_date_localized']      # Site-wide last revision date
page.meta['git_site_revision_date_localized_hash'] # Site-wide last revision hash
page.meta['git_site_revision_date_localized_tag']  # Site-wide last revision tag

# Site-wide raw date formats
page.meta['git_site_revision_date_localized_raw_date']        # Site raw date format
page.meta['git_site_revision_date_localized_raw_datetime']    # Site raw datetime format
page.meta['git_site_revision_date_localized_raw_iso_date']    # Site raw ISO date
page.meta['git_site_revision_date_localized_raw_iso_datetime'] # Site raw ISO datetime
page.meta['git_site_revision_date_localized_raw_timeago']     # Site raw timeago
page.meta['git_site_revision_date_localized_raw_custom']      # Site raw custom format

# Creation date information (when enable_creation_date is True)
page.meta['git_creation_date_localized']          # Formatted creation date
page.meta['git_creation_date_localized_hash']     # Creation commit hash
page.meta['git_creation_date_localized_tag']      # Creation commit tag (if any)

# Creation date raw formats
page.meta['git_creation_date_localized_raw_date']        # Raw creation date format
page.meta['git_creation_date_localized_raw_datetime']    # Raw creation datetime format
page.meta['git_creation_date_localized_raw_iso_date']    # Raw creation ISO date
page.meta['git_creation_date_localized_raw_iso_datetime'] # Raw creation ISO datetime
page.meta['git_creation_date_localized_raw_timeago']     # Raw creation timeago
page.meta['git_creation_date_localized_raw_custom']      # Raw creation custom format

Usage in Templates:

<!-- Last updated information -->
<p>Last updated: {{ page.meta.git_revision_date_localized }}</p>
<p>Commit: {{ page.meta.git_revision_date_localized_hash }}</p>

<!-- Creation date (if enabled) -->
{% if page.meta.git_creation_date_localized %}
<p>Created: {{ page.meta.git_creation_date_localized }}</p>
{% endif %}

<!-- Site-wide information -->
<p>Site last updated: {{ page.meta.git_site_revision_date_localized }}</p>

<!-- Using raw formats for custom display -->
<time datetime="{{ page.meta.git_revision_date_localized_raw_iso_datetime }}">
  {{ page.meta.git_revision_date_localized_raw_date }}
</time>

Markdown Template Tags

Template tags that are processed and replaced in markdown content during the build process.

# Template tags processed in markdown files
"{{ git_revision_date_localized }}"      # Replaced with formatted last revision date
"{{ git_site_revision_date_localized }}" # Replaced with site-wide last revision date
"{{ git_creation_date_localized }}"      # Replaced with creation date (if enabled)

Usage in Markdown:

# My Document

This document was last updated on {{ git_revision_date_localized }}.

The entire site was last updated on {{ git_site_revision_date_localized }}.

{% if enable_creation_date %}
This document was created on {{ git_creation_date_localized }}.
{% endif %}

Theme Integration Examples

Examples of how to integrate revision dates in popular MkDocs themes.

MkDocs Material Theme:

<!-- In a custom template override -->
{% if page.meta.git_revision_date_localized %}
  <div class="md-source-date">
    <small>Last update: {{ page.meta.git_revision_date_localized }}</small>
  </div>
{% endif %}

Custom CSS for Timeago:

/* Timeago-specific styling */
.git-revision-date-localized-plugin {
  font-size: 0.8em;
  color: var(--md-default-fg-color--light);
}

.git-revision-date-localized-plugin-timeago {
  font-style: italic;
}

/* Print fallback for timeago */
@media print {
  .timeago {
    display: none;
  }
  .git-revision-date-localized-plugin-iso_date {
    display: inline !important;
  }
}

ReadTheDocs Theme:

<!-- In footer template -->
<div class="rst-footer-buttons">
  {% if page.meta.git_revision_date_localized %}
    <div class="revision-date">
      Last updated: {{ page.meta.git_revision_date_localized }}
    </div>
  {% endif %}
</div>

Locale Support

The plugin supports locale detection from multiple sources with priority order:

# Locale detection priority (highest to lowest):
# 1. Plugin configuration: locale parameter
# 2. mkdocs-static-i18n: page.file.locale
# 3. Page frontmatter: locale metadata
# 4. Theme configuration: language or locale setting
# 5. Fallback: "en" (English)

Setting Locale via Frontmatter:

---
locale: fr
---

# Mon Document

Ce document a été mis à jour le {{ git_revision_date_localized }}.

mkdocs-static-i18n Integration:

plugins:
  - i18n:
      default_language: en
      languages:
        en: English
        fr: Français
  - git-revision-date-localized  # Must come after i18n plugin

Dynamic Timeago Integration

For timeago format, the plugin automatically includes JavaScript and CSS assets.

# Automatically added when type: timeago
config["extra_javascript"] = ["js/timeago_mkdocs_material.js"] + config["extra_javascript"]
config["extra_javascript"] = ["js/timeago.min.js"] + config["extra_javascript"]
config["extra_css"] = ["css/timeago.css"] + config["extra_css"]

JavaScript Integration:

// timeago_mkdocs_material.js handles:
// - Locale mapping for timeago.js
// - MkDocs Material instant loading compatibility
// - Automatic rendering of .timeago elements

function getLocale(element) {
    var raw_locale = element.getAttribute('locale');
    // Maps locale codes to timeago.js format
    var locale = {
        bn: 'bn_IN',
        en: 'en_US',
        hi: 'hi_IN',
        // ... more mappings
    }[raw_locale];
    return locale ? locale : raw_locale;
}

Usage Examples

Basic Page Footer

<footer>
  {% if page.meta.git_revision_date_localized %}
    <p class="revision-info">
      Last updated: {{ page.meta.git_revision_date_localized }}
      {% if page.meta.git_revision_date_localized_tag %}
        ({{ page.meta.git_revision_date_localized_tag }})
      {% endif %}
    </p>
  {% endif %}
</footer>

Structured Data for SEO

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "dateModified": "{{ page.meta.git_revision_date_localized_raw_iso_datetime }}",
  "datePublished": "{{ page.meta.git_creation_date_localized_raw_iso_datetime or page.meta.git_revision_date_localized_raw_iso_datetime }}"
}
</script>

Multi-language Site

{% set revision_date = page.meta.git_revision_date_localized %}
{% if page.file.locale == 'fr' %}
  <p>Dernière mise à jour : {{ revision_date }}</p>
{% elif page.file.locale == 'de' %}
  <p>Zuletzt aktualisiert: {{ revision_date }}</p>
{% else %}
  <p>Last updated: {{ revision_date }}</p>
{% endif %}

Install with Tessl CLI

npx tessl i tessl/pypi-mkdocs-git-revision-date-localized-plugin

docs

configuration.md

git-operations.md

index.md

template-integration.md

utilities.md

tile.json