0
# MkDocs Git Revision Date Localized Plugin
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: mkdocs-git-revision-date-localized-plugin
7
- **Package Type**: MkDocs Plugin
8
- **Language**: Python
9
- **Installation**: `pip install mkdocs-git-revision-date-localized-plugin`
10

11
## Core Imports
12

13
```python
14
from mkdocs_git_revision_date_localized_plugin.plugin import GitRevisionDateLocalizedPlugin
15
```
16

17
For direct utility usage:
18

19
```python
20
from mkdocs_git_revision_date_localized_plugin.util import Util
21
from mkdocs_git_revision_date_localized_plugin.dates import get_date_formats, strftime_to_babel_format
22
from mkdocs_git_revision_date_localized_plugin.exclude import exclude
23
from mkdocs_git_revision_date_localized_plugin.ci import raise_ci_warnings, is_shallow_clone, commit_count
24
from mkdocs_git_revision_date_localized_plugin import __version__
25
```
26

27
## Basic Usage
28

29
Add to your `mkdocs.yml`:
30

31
```yaml
32
plugins:
33
  - search
34
  - git-revision-date-localized:
35
      type: date
36
      locale: en
37
      timezone: UTC
38
```
39

40
Use in markdown templates:
41

42
```markdown
43
Last updated: {{ git_revision_date_localized }}
44
```
45

46
Access in templates:
47

48
```html
49
<p>Last updated: {{ page.meta.git_revision_date_localized }}</p>
50
```
51

52
## Architecture
53

54
The plugin follows MkDocs' standard plugin architecture:
55

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

62
## Capabilities
63

64
### Plugin Configuration
65

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

68
```python { .api }
69
config_scheme = (
70
    ("fallback_to_build_date", config_options.Type(bool, default=False)),
71
    ("locale", config_options.Type(str, default=None)),
72
    ("type", config_options.Type(str, default="date")),
73
    ("custom_format", config_options.Type(str, default="%d. %B %Y")),
74
    ("timezone", config_options.Type(str, default="UTC")),
75
    ("exclude", config_options.Type(list, default=[])),
76
    ("enable_creation_date", config_options.Type(bool, default=False)),
77
    ("enabled", config_options.Type(bool, default=True)),
78
    ("strict", config_options.Type(bool, default=True)),
79
    ("enable_git_follow", config_options.Type(bool, default=True)),
80
    ("ignored_commits_file", config_options.Type(str, default=None)),
81
    ("enable_parallel_processing", config_options.Type(bool, default=True)),
82
)
83
```
84

85
[Plugin Configuration](./configuration.md)
86

87
### Git Operations & Date Formatting
88

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

91
```python { .api }
92
class Util:
93
    def __init__(self, config: Dict, mkdocs_dir: str): ...
94
    def get_git_commit_timestamp(self, path: str, is_first_commit: bool = False) -> Tuple[str, int]: ...
95
    def get_date_formats_for_timestamp(self, commit_timestamp: int, locale: str, add_spans: bool = True) -> Dict[str, str]: ...
96
    def get_tag_name_for_commit(self, commit_hash: str) -> str: ...
97

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

101
[Git Operations & Date Formatting](./git-operations.md)
102

103
### Template Variables & Tags
104

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

107
```python { .api }
108
# Page metadata variables automatically added by plugin
109
page.meta['git_revision_date_localized']  # Formatted revision date
110
page.meta['git_revision_date_localized_hash']  # Commit hash
111
page.meta['git_creation_date_localized']  # Creation date (if enabled)
112
# ... plus many more metadata variables
113

114
# Template tags processed in markdown
115
{{ git_revision_date_localized }}
116
{{ git_site_revision_date_localized }}
117
{{ git_creation_date_localized }}
118
```
119

120
[Template Variables & Tags](./template-integration.md)
121

122
### File Exclusion & CI Integration
123

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

126
```python { .api }
127
def exclude(src_path: str, globs: List[str]) -> bool: ...
128

129
def raise_ci_warnings(repo) -> None: ...
130
def is_shallow_clone(repo) -> bool: ...
131
def commit_count(repo) -> int: ...
132
```
133

134
[File Exclusion & CI Integration](./utilities.md)
135

136
## Types
137

138
```python { .api }
139
class GitRevisionDateLocalizedPlugin(BasePlugin):
140
    """Main plugin class implementing MkDocs BasePlugin interface"""
141
    config_scheme: Tuple  # Configuration schema
142
    
143
    def __init__(self): ...
144
    def on_config(self, config: config_options.Config, **kwargs) -> Dict[str, Any]: ...
145
    def on_files(self, files: Files, config: MkDocsConfig): ...
146
    def on_page_markdown(self, markdown: str, page: Page, config: config_options.Config, files, **kwargs) -> str: ...
147
    def on_post_build(self, config: Dict[str, Any], **kwargs) -> None: ...
148
    def parallel_compute_commit_timestamps(self, files, original_source: Optional[Dict] = None, is_first_commit: bool = False): ...
149

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

156
# Package metadata
157
__version__: str  # Package version string
158
```