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
git-operations.mddocs/
Git Operations & Date Formatting
Core utilities for extracting git commit timestamps, handling repository operations, and formatting dates in various localized formats. These functions form the foundation of the plugin's ability to retrieve and display git revision information.
Capabilities
Git Repository Operations
Core git operations for extracting commit information and handling repository state.
class Util:
def __init__(self, config: Dict, mkdocs_dir: str):
"""
Initialize utility class for git operations.
Parameters:
- config (Dict): Plugin configuration dictionary
- mkdocs_dir (str): Path to MkDocs directory
"""
def get_git_commit_timestamp(self, path: str, is_first_commit: bool = False) -> Tuple[str, int]:
"""
Get git commit timestamp for a file.
Parameters:
- path (str): File path to get commit info for
- is_first_commit (bool): If True, get creation commit; if False, get latest commit
Returns:
Tuple[str, int]: (commit_hash, unix_timestamp)
"""
def get_tag_name_for_commit(self, commit_hash: str) -> str:
"""
Get git tag name for a specific commit.
Parameters:
- commit_hash (str): Git commit hash
Returns:
str: Tag name or empty string if no tag found
"""Usage:
from mkdocs_git_revision_date_localized_plugin.util import Util
# Initialize utility
config = {"timezone": "UTC", "enable_git_follow": True}
util = Util(config, "/path/to/mkdocs/dir")
# Get latest commit info
commit_hash, timestamp = util.get_git_commit_timestamp("/path/to/file.md")
# Get creation commit info
first_hash, first_timestamp = util.get_git_commit_timestamp("/path/to/file.md", is_first_commit=True)
# Get tag for commit
tag_name = util.get_tag_name_for_commit(commit_hash)Date Formatting Functions
Functions for converting timestamps to various localized date formats.
def get_date_formats(unix_timestamp: float, locale: str = "en", time_zone: str = "UTC", custom_format: str = "%d. %B %Y") -> Dict[str, Any]:
"""
Calculate different date formats for a timestamp.
Parameters:
- unix_timestamp (float): Unix timestamp in seconds
- locale (str): Locale code for language (e.g., "en", "fr", "de")
- time_zone (str): Timezone name (e.g., "UTC", "America/New_York")
- custom_format (str): strftime format for custom type
Returns:
Dict[str, Any]: Dictionary with date format keys and formatted strings
"""
def strftime_to_babel_format(fmt: str) -> str:
"""
Convert strftime format string to Babel format pattern.
Parameters:
- fmt (str): strftime format string
Returns:
str: Babel format pattern
"""Usage:
from mkdocs_git_revision_date_localized_plugin.dates import get_date_formats, strftime_to_babel_format
import time
# Get current timestamp
timestamp = time.time()
# Format in different locales
english_dates = get_date_formats(timestamp, locale="en", time_zone="UTC")
french_dates = get_date_formats(timestamp, locale="fr", time_zone="Europe/Paris")
# Available format types
print(english_dates["date"]) # "January 15, 2023"
print(english_dates["datetime"]) # "January 15, 2023 14:30:25"
print(english_dates["iso_date"]) # "2023-01-15"
print(english_dates["iso_datetime"]) # "2023-01-15 14:30:25"
print(english_dates["timeago"]) # '<span class="timeago" datetime="2023-01-15T14:30:25+00:00" locale="en"></span>'
print(english_dates["custom"]) # "15. January 2023"
# Convert strftime to Babel format
babel_format = strftime_to_babel_format("%Y-%m-%d %H:%M") # Returns "yyyy-MM-dd HH:mm"Utility Date Formatting Methods
Instance methods for formatting dates with plugin configuration context.
class Util:
def get_date_formats_for_timestamp(self, commit_timestamp: int, locale: str, add_spans: bool = True) -> Dict[str, str]:
"""
Get localized date formats for a timestamp using plugin configuration.
Parameters:
- commit_timestamp (int): Unix timestamp
- locale (str): Locale code
- add_spans (bool): Whether to wrap dates in HTML spans
Returns:
Dict[str, str]: Formatted date strings by type
"""
@staticmethod
def add_spans(date_formats: Dict[str, str]) -> Dict[str, str]:
"""
Wrap date strings in HTML spans with CSS classes.
Parameters:
- date_formats (Dict[str, str]): Date formats dictionary
Returns:
Dict[str, str]: Date formats wrapped in HTML spans
"""Usage:
# Using Util instance methods
util = Util(config, mkdocs_dir)
commit_hash, timestamp = util.get_git_commit_timestamp("file.md")
# Get formatted dates with spans
dates_with_spans = util.get_date_formats_for_timestamp(timestamp, "en", add_spans=True)
# Get raw date strings without spans
raw_dates = util.get_date_formats_for_timestamp(timestamp, "en", add_spans=False)Git Ignore Revisions
Utility for parsing and handling ignored commit lists.
class Util:
@staticmethod
def parse_git_ignore_revs(filename: str) -> List[str]:
"""
Parse git blame ignore revisions file.
Parameters:
- filename (str): Path to ignore revisions file
Returns:
List[str]: List of commit hashes to ignore
"""Usage:
# Parse ignore file (same format as git's blame.ignoreRevsFile)
ignored_commits = Util.parse_git_ignore_revs(".git-blame-ignore-revs")Date Format Reference
The date formatting functions return dictionaries with these keys:
- date: Localized long date (e.g., "15 janvier 2023" in French)
- datetime: Date with time (e.g., "15 janvier 2023 14:30:25")
- datetime-timezone: Date with time and timezone (e.g., "15 janvier 2023 14:30:25 CET")
- iso_date: ISO date format (e.g., "2023-01-15")
- iso_datetime: ISO datetime format (e.g., "2023-01-15 14:30:25")
- timeago: HTML span for timeago.js (e.g.,
<span class="timeago" datetime="..." locale="fr"></span>) - custom: Custom format using provided format string
Error Handling
The git operations handle various error conditions:
- InvalidGitRepositoryError: When directory is not a git repository
- GitCommandError: When git commands fail
- GitCommandNotFound: When git is not installed
- NoSuchPathError: When file path doesn't exist
All errors can be handled gracefully using the fallback_to_build_date configuration option.
Install with Tessl CLI
npx tessl i tessl/pypi-mkdocs-git-revision-date-localized-plugin