0
# Template Variables & Tags
1

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

4
## Capabilities
5

6
### Page Metadata Variables
7

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

10
```python { .api }
11
# Last revision date information
12
page.meta['git_revision_date_localized']          # Formatted last revision date
13
page.meta['git_revision_date_localized_hash']     # Commit hash of last revision
14
page.meta['git_revision_date_localized_tag']      # Git tag for last revision (if any)
15

16
# Raw date formats for last revision (without HTML spans)
17
page.meta['git_revision_date_localized_raw_date']        # Raw date format
18
page.meta['git_revision_date_localized_raw_datetime']    # Raw datetime format
19
page.meta['git_revision_date_localized_raw_iso_date']    # Raw ISO date format
20
page.meta['git_revision_date_localized_raw_iso_datetime'] # Raw ISO datetime format
21
page.meta['git_revision_date_localized_raw_timeago']     # Raw timeago format
22
page.meta['git_revision_date_localized_raw_custom']      # Raw custom format
23

24
# Site-wide last revision information
25
page.meta['git_site_revision_date_localized']      # Site-wide last revision date
26
page.meta['git_site_revision_date_localized_hash'] # Site-wide last revision hash
27
page.meta['git_site_revision_date_localized_tag']  # Site-wide last revision tag
28

29
# Site-wide raw date formats
30
page.meta['git_site_revision_date_localized_raw_date']        # Site raw date format
31
page.meta['git_site_revision_date_localized_raw_datetime']    # Site raw datetime format
32
page.meta['git_site_revision_date_localized_raw_iso_date']    # Site raw ISO date
33
page.meta['git_site_revision_date_localized_raw_iso_datetime'] # Site raw ISO datetime
34
page.meta['git_site_revision_date_localized_raw_timeago']     # Site raw timeago
35
page.meta['git_site_revision_date_localized_raw_custom']      # Site raw custom format
36

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

42
# Creation date raw formats
43
page.meta['git_creation_date_localized_raw_date']        # Raw creation date format
44
page.meta['git_creation_date_localized_raw_datetime']    # Raw creation datetime format
45
page.meta['git_creation_date_localized_raw_iso_date']    # Raw creation ISO date
46
page.meta['git_creation_date_localized_raw_iso_datetime'] # Raw creation ISO datetime
47
page.meta['git_creation_date_localized_raw_timeago']     # Raw creation timeago
48
page.meta['git_creation_date_localized_raw_custom']      # Raw creation custom format
49
```
50

51
**Usage in Templates:**
52

53
```html
54
<!-- Last updated information -->
55
<p>Last updated: {{ page.meta.git_revision_date_localized }}</p>
56
<p>Commit: {{ page.meta.git_revision_date_localized_hash }}</p>
57

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

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

66
<!-- Using raw formats for custom display -->
67
<time datetime="{{ page.meta.git_revision_date_localized_raw_iso_datetime }}">
68
  {{ page.meta.git_revision_date_localized_raw_date }}
69
</time>
70
```
71

72
### Markdown Template Tags
73

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

76
```python { .api }
77
# Template tags processed in markdown files
78
"{{ git_revision_date_localized }}"      # Replaced with formatted last revision date
79
"{{ git_site_revision_date_localized }}" # Replaced with site-wide last revision date
80
"{{ git_creation_date_localized }}"      # Replaced with creation date (if enabled)
81
```
82

83
**Usage in Markdown:**
84

85
```markdown
86
# My Document
87

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

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

92
{% if enable_creation_date %}
93
This document was created on {{ git_creation_date_localized }}.
94
{% endif %}
95
```
96

97
### Theme Integration Examples
98

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

101
**MkDocs Material Theme:**
102

103
```html
104
<!-- In a custom template override -->
105
{% if page.meta.git_revision_date_localized %}
106
  <div class="md-source-date">
107
    <small>Last update: {{ page.meta.git_revision_date_localized }}</small>
108
  </div>
109
{% endif %}
110
```
111

112
**Custom CSS for Timeago:**
113

114
```css
115
/* Timeago-specific styling */
116
.git-revision-date-localized-plugin {
117
  font-size: 0.8em;
118
  color: var(--md-default-fg-color--light);
119
}
120

121
.git-revision-date-localized-plugin-timeago {
122
  font-style: italic;
123
}
124

125
/* Print fallback for timeago */
126
@media print {
127
  .timeago {
128
    display: none;
129
  }
130
  .git-revision-date-localized-plugin-iso_date {
131
    display: inline !important;
132
  }
133
}
134
```
135

136
**ReadTheDocs Theme:**
137

138
```html
139
<!-- In footer template -->
140
<div class="rst-footer-buttons">
141
  {% if page.meta.git_revision_date_localized %}
142
    <div class="revision-date">
143
      Last updated: {{ page.meta.git_revision_date_localized }}
144
    </div>
145
  {% endif %}
146
</div>
147
```
148

149
### Locale Support
150

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

153
```python { .api }
154
# Locale detection priority (highest to lowest):
155
# 1. Plugin configuration: locale parameter
156
# 2. mkdocs-static-i18n: page.file.locale
157
# 3. Page frontmatter: locale metadata
158
# 4. Theme configuration: language or locale setting
159
# 5. Fallback: "en" (English)
160
```
161

162
**Setting Locale via Frontmatter:**
163

164
```markdown
165
---
166
locale: fr
167
---
168

169
# Mon Document
170

171
Ce document a été mis à jour le {{ git_revision_date_localized }}.
172
```
173

174
**mkdocs-static-i18n Integration:**
175

176
```yaml
177
plugins:
178
  - i18n:
179
      default_language: en
180
      languages:
181
        en: English
182
        fr: Français
183
  - git-revision-date-localized  # Must come after i18n plugin
184
```
185

186
### Dynamic Timeago Integration
187

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

190
```python { .api }
191
# Automatically added when type: timeago
192
config["extra_javascript"] = ["js/timeago_mkdocs_material.js"] + config["extra_javascript"]
193
config["extra_javascript"] = ["js/timeago.min.js"] + config["extra_javascript"]
194
config["extra_css"] = ["css/timeago.css"] + config["extra_css"]
195
```
196

197
**JavaScript Integration:**
198

199
```javascript
200
// timeago_mkdocs_material.js handles:
201
// - Locale mapping for timeago.js
202
// - MkDocs Material instant loading compatibility
203
// - Automatic rendering of .timeago elements
204

205
function getLocale(element) {
206
    var raw_locale = element.getAttribute('locale');
207
    // Maps locale codes to timeago.js format
208
    var locale = {
209
        bn: 'bn_IN',
210
        en: 'en_US',
211
        hi: 'hi_IN',
212
        // ... more mappings
213
    }[raw_locale];
214
    return locale ? locale : raw_locale;
215
}
216
```
217

218
## Usage Examples
219

220
### Basic Page Footer
221

222
```html
223
<footer>
224
  {% if page.meta.git_revision_date_localized %}
225
    <p class="revision-info">
226
      Last updated: {{ page.meta.git_revision_date_localized }}
227
      {% if page.meta.git_revision_date_localized_tag %}
228
        ({{ page.meta.git_revision_date_localized_tag }})
229
      {% endif %}
230
    </p>
231
  {% endif %}
232
</footer>
233
```
234

235
### Structured Data for SEO
236

237
```html
238
<script type="application/ld+json">
239
{
240
  "@context": "https://schema.org",
241
  "@type": "Article",
242
  "dateModified": "{{ page.meta.git_revision_date_localized_raw_iso_datetime }}",
243
  "datePublished": "{{ page.meta.git_creation_date_localized_raw_iso_datetime or page.meta.git_revision_date_localized_raw_iso_datetime }}"
244
}
245
</script>
246
```
247

248
### Multi-language Site
249

250
```html
251
{% set revision_date = page.meta.git_revision_date_localized %}
252
{% if page.file.locale == 'fr' %}
253
  <p>Dernière mise à jour : {{ revision_date }}</p>
254
{% elif page.file.locale == 'de' %}
255
  <p>Zuletzt aktualisiert: {{ revision_date }}</p>
256
{% else %}
257
  <p>Last updated: {{ revision_date }}</p>
258
{% endif %}
259
```