or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdgit-operations.mdindex.mdtemplate-integration.mdutilities.md
tile.json

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.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/mkdocs-git-revision-date-localized-plugin@1.4.x

To install, run

npx @tessl/cli install tessl/pypi-mkdocs-git-revision-date-localized-plugin@1.4.0

index.mddocs/

MkDocs Git Revision Date Localized Plugin

An MkDocs plugin that automatically displays the localized date of the last git modification of markdown files. The plugin integrates with git history to extract commit dates, uses Babel for internationalization, and provides dynamic date formatting through timeago.js.

Package Information

  • Package Name: mkdocs-git-revision-date-localized-plugin
  • Package Type: MkDocs Plugin
  • Language: Python
  • Installation: pip install mkdocs-git-revision-date-localized-plugin

Core Imports

from mkdocs_git_revision_date_localized_plugin.plugin import GitRevisionDateLocalizedPlugin

For direct utility usage:

from mkdocs_git_revision_date_localized_plugin.util import Util
from mkdocs_git_revision_date_localized_plugin.dates import get_date_formats, strftime_to_babel_format
from mkdocs_git_revision_date_localized_plugin.exclude import exclude
from mkdocs_git_revision_date_localized_plugin.ci import raise_ci_warnings, is_shallow_clone, commit_count
from mkdocs_git_revision_date_localized_plugin import __version__

Basic Usage

Add to your mkdocs.yml:

plugins:
  - search
  - git-revision-date-localized:
      type: date
      locale: en
      timezone: UTC

Use in markdown templates:

Last updated: {{ git_revision_date_localized }}

Access in templates:

<p>Last updated: {{ page.meta.git_revision_date_localized }}</p>

Architecture

The plugin follows MkDocs' standard plugin architecture:

  • Plugin Class: Implements MkDocs BasePlugin with lifecycle hooks
  • Util Class: Handles git operations and date formatting
  • Date Functions: Provide localized date formatting via Babel
  • Template Integration: Exposes variables and processes template tags
  • Asset Management: Manages timeago.js JavaScript and CSS assets

Capabilities

Plugin Configuration

Comprehensive configuration options for customizing date display behavior, localization, timezone handling, file exclusion, and performance optimization.

config_scheme = (
    ("fallback_to_build_date", config_options.Type(bool, default=False)),
    ("locale", config_options.Type(str, default=None)),
    ("type", config_options.Type(str, default="date")),
    ("custom_format", config_options.Type(str, default="%d. %B %Y")),
    ("timezone", config_options.Type(str, default="UTC")),
    ("exclude", config_options.Type(list, default=[])),
    ("enable_creation_date", config_options.Type(bool, default=False)),
    ("enabled", config_options.Type(bool, default=True)),
    ("strict", config_options.Type(bool, default=True)),
    ("enable_git_follow", config_options.Type(bool, default=True)),
    ("ignored_commits_file", config_options.Type(str, default=None)),
    ("enable_parallel_processing", config_options.Type(bool, default=True)),
)

Plugin Configuration

Git Operations & Date Formatting

Core utilities for extracting git commit timestamps, handling repository operations, and formatting dates in various localized formats.

class Util:
    def __init__(self, config: Dict, mkdocs_dir: str): ...
    def get_git_commit_timestamp(self, path: str, is_first_commit: bool = False) -> Tuple[str, int]: ...
    def get_date_formats_for_timestamp(self, commit_timestamp: int, locale: str, add_spans: bool = True) -> Dict[str, str]: ...
    def get_tag_name_for_commit(self, commit_hash: str) -> str: ...

def get_date_formats(unix_timestamp: float, locale: str = "en", time_zone: str = "UTC", custom_format: str = "%d. %B %Y") -> Dict[str, Any]: ...

Git Operations & Date Formatting

Template Variables & Tags

Template integration providing access to git revision information through page metadata variables and markdown template tags.

# Page metadata variables automatically added by plugin
page.meta['git_revision_date_localized']  # Formatted revision date
page.meta['git_revision_date_localized_hash']  # Commit hash
page.meta['git_creation_date_localized']  # Creation date (if enabled)
# ... plus many more metadata variables

# Template tags processed in markdown
{{ git_revision_date_localized }}
{{ git_site_revision_date_localized }}
{{ git_creation_date_localized }}

Template Variables & Tags

File Exclusion & CI Integration

Utilities for excluding files from processing and handling CI/CD environment considerations for proper git history access.

def exclude(src_path: str, globs: List[str]) -> bool: ...

def raise_ci_warnings(repo) -> None: ...
def is_shallow_clone(repo) -> bool: ...
def commit_count(repo) -> int: ...

File Exclusion & CI Integration

Types

class GitRevisionDateLocalizedPlugin(BasePlugin):
    """Main plugin class implementing MkDocs BasePlugin interface"""
    config_scheme: Tuple  # Configuration schema
    
    def __init__(self): ...
    def on_config(self, config: config_options.Config, **kwargs) -> Dict[str, Any]: ...
    def on_files(self, files: Files, config: MkDocsConfig): ...
    def on_page_markdown(self, markdown: str, page: Page, config: config_options.Config, files, **kwargs) -> str: ...
    def on_post_build(self, config: Dict[str, Any], **kwargs) -> None: ...
    def parallel_compute_commit_timestamps(self, files, original_source: Optional[Dict] = None, is_first_commit: bool = False): ...

class Util:
    """Utility class for git operations and date formatting"""
    def __init__(self, config: Dict, mkdocs_dir: str): ...
    repo_cache: Dict[str, Any]  # Cached git repositories
    ignored_commits: List[str]  # List of ignored commit hashes

# Package metadata
__version__: str  # Package version string