0
# Built-in Context
1
2
Predefined variables and context objects automatically available in templates, including environment information, git data, page metadata, and site configuration.
3
4
## Capabilities
5
6
### System Environment Variables
7
8
Information about the system environment, versions, and runtime context.
9
10
```python { .api }
11
environment: dict = {
12
'system': str, # Operating system name ('Linux', 'Windows', 'MacOs')
13
'system_version': str, # OS version string
14
'python_version': str, # Python version string
15
'mkdocs_version': str, # MkDocs version
16
'macros_plugin_version': str, # Plugin version
17
'jinja2_version': str # Jinja2 version
18
}
19
```
20
21
#### Usage Examples
22
23
System-specific content:
24
```markdown
25
Running on {{ environment.system }} {{ environment.system_version }}
26
Built with Python {{ environment.python_version }}
27
28
{% if environment.system == 'Windows' %}
29
Use `copy` command instead of `cp`.
30
{% else %}
31
Use standard Unix commands.
32
{% endif %}
33
```
34
35
Version information:
36
```markdown
37
Documentation built with:
38
- MkDocs {{ environment.mkdocs_version }}
39
- MkDocs Macros {{ environment.macros_plugin_version }}
40
- Python {{ environment.python_version }}
41
```
42
43
### Plugin Configuration
44
45
Access to the plugin's configuration from mkdocs.yml.
46
47
```python { .api }
48
plugin: dict # Complete plugin configuration from mkdocs.yml macros section
49
```
50
51
#### Usage Examples
52
53
Configuration-based content:
54
```markdown
55
{% if plugin.verbose %}
56
Debug mode is enabled.
57
{% endif %}
58
59
Module name: {{ plugin.module_name }}
60
61
{% if plugin.include_dir %}
62
Templates loaded from: {{ plugin.include_dir }}
63
{% endif %}
64
```
65
66
### Git Repository Information
67
68
Git repository metadata and commit information.
69
70
```python { .api }
71
git: dict = {
72
'status': bool, # True if git information was successfully retrieved
73
'commit': str, # Full commit hash
74
'short_commit': str, # Abbreviated commit hash
75
'tag': str, # Current git tag (if any)
76
'short_tag': str, # Tag without version suffix
77
'author': str, # Last commit author name
78
'author_email': str, # Last commit author email
79
'committer': str, # Last commit committer name
80
'committer_email': str, # Last commit committer email
81
'date': datetime, # Last commit date as datetime object
82
'date_ISO': str, # Last commit date as ISO string
83
'message': str, # Last commit message
84
'raw': str, # Raw git log output
85
'root_dir': str # Git repository root directory
86
}
87
```
88
89
#### Usage Examples
90
91
Commit information:
92
```markdown
93
Last updated: {{ git.date.strftime('%Y-%m-%d') }}
94
Commit: {{ git.short_commit }}
95
96
{% if git.tag %}
97
Version: {{ git.short_tag }}
98
{% endif %}
99
100
{% if git.status %}
101
Repository: {{ git.root_dir }}
102
Author: {{ git.author }}
103
{% else %}
104
Not a git repository
105
{% endif %}
106
```
107
108
Build metadata:
109
```markdown
110
---
111
Built from commit [{{ git.short_commit }}]({{ config.repo_url }}/commit/{{ git.commit }})
112
on {{ git.date.strftime('%B %d, %Y') }}
113
---
114
```
115
116
### Site Configuration
117
118
Complete MkDocs configuration with all settings and metadata.
119
120
```python { .api }
121
config: dict # Complete mkdocs.yml configuration
122
```
123
124
#### Usage Examples
125
126
Site information:
127
```markdown
128
# {{ config.site_name }}
129
130
{{ config.site_description }}
131
132
{% if config.site_url %}
133
Visit us at: {{ config.site_url }}
134
{% endif %}
135
136
{% if config.repo_url %}
137
Source code: [{{ config.repo_name }}]({{ config.repo_url }})
138
{% endif %}
139
```
140
141
Theme and plugin configuration:
142
```markdown
143
{% if config.theme.name == 'material' %}
144
Using Material theme with features:
145
{% for feature in config.theme.features %}
146
- {{ feature }}
147
{% endfor %}
148
{% endif %}
149
150
Active plugins:
151
{% for plugin in config.plugins %}
152
- {{ plugin }}
153
{% endfor %}
154
```
155
156
### Extra Variables
157
158
Variables defined in the extra section of mkdocs.yml.
159
160
```python { .api }
161
extra: dict # Variables from mkdocs.yml extra section
162
# Also available as top-level variables
163
```
164
165
#### Usage Examples
166
167
mkdocs.yml:
168
```yaml
169
extra:
170
version: '2.1.0'
171
author: 'John Doe'
172
social:
173
twitter: '@johndoe'
174
github: 'johndoe'
175
```
176
177
Template usage:
178
```markdown
179
Version: {{ version }} <!-- or {{ extra.version }} -->
180
Author: {{ author }}
181
182
Follow us:
183
- [Twitter](https://twitter.com/{{ social.twitter }})
184
- [GitHub](https://github.com/{{ social.github }})
185
```
186
187
### Page Context
188
189
Current page metadata and properties (available during page rendering).
190
191
```python { .api }
192
page: Page = {
193
'title': str, # Page title
194
'url': str, # Page URL
195
'abs_url': str, # Absolute page URL
196
'canonical_url': str, # Canonical URL
197
'edit_url': str, # Edit URL (if configured)
198
'file': File, # File object with path information
199
'content': str, # Rendered page content (HTML)
200
'toc': list, # Table of contents
201
'meta': dict, # Page metadata from YAML front matter
202
'previous_page': Page, # Previous page in navigation
203
'next_page': Page # Next page in navigation
204
}
205
```
206
207
#### Usage Examples
208
209
Page metadata:
210
```markdown
211
# {{ page.title }}
212
213
{% if page.meta.description %}
214
{{ page.meta.description }}
215
{% endif %}
216
217
File: `{{ page.file.src_path }}`
218
219
{% if page.edit_url %}
220
[Edit this page]({{ page.edit_url }})
221
{% endif %}
222
```
223
224
Navigation:
225
```markdown
226
{% if page.previous_page %}
227
← [{{ page.previous_page.title }}]({{ page.previous_page.url }})
228
{% endif %}
229
230
{% if page.next_page %}
231
[{{ page.next_page.title }}]({{ page.next_page.url }}) →
232
{% endif %}
233
```
234
235
Page-specific logic:
236
```markdown
237
{% if page.file.src_path.startswith('api/') %}
238
This is an API documentation page.
239
{% endif %}
240
241
{% if 'draft' in page.meta %}
242
⚠️ This page is a draft
243
{% endif %}
244
```
245
246
### Site Navigation
247
248
Complete site navigation structure with all pages and sections.
249
250
```python { .api }
251
navigation: Navigation # Site navigation object with pages and hierarchy
252
```
253
254
#### Usage Examples
255
256
Navigation menu:
257
```markdown
258
## Site Contents
259
260
{% for item in navigation.items %}
261
{% if item.is_page %}
262
- [{{ item.title }}]({{ item.url }})
263
{% elif item.is_section %}
264
- {{ item.title }}
265
{% for child in item.children %}
266
- [{{ child.title }}]({{ child.url }})
267
{% endfor %}
268
{% endif %}
269
{% endfor %}
270
```
271
272
Page count:
273
```markdown
274
This site contains {{ navigation.pages | length }} pages.
275
```
276
277
### Site Files
278
279
Collection of all files in the site.
280
281
```python { .api }
282
files: Files # Collection of all site files
283
```
284
285
#### Usage Examples
286
287
File listing:
288
```markdown
289
## All Files
290
291
{% for file in files %}
292
- {{ file.src_path }} → {{ file.dest_path }}
293
{% endfor %}
294
```
295
296
Conditional includes:
297
```markdown
298
{% for file in files %}
299
{% if file.name == 'changelog.md' %}
300
{% include file.src_path %}
301
{% endif %}
302
{% endfor %}
303
```
304
305
## Variable Hierarchy
306
307
Variables are resolved in this order (later overrides earlier):
308
309
1. Built-in variables (environment, git, config, etc.)
310
2. Extra variables from mkdocs.yml
311
3. Variables from included YAML files
312
4. Variables from Python modules
313
5. Page-level variables from YAML front matter
314
6. Template-level variables from `{% set %}` statements
315
316
## Accessing Nested Data
317
318
All built-in variables support nested access:
319
320
```markdown
321
<!-- Dot notation -->
322
{{ config.theme.name }}
323
{{ git.date.year }}
324
{{ page.file.src_path }}
325
326
<!-- Bracket notation -->
327
{{ config['site_name'] }}
328
{{ environment['python_version'] }}
329
330
<!-- With defaults -->
331
{{ config.repo_name | default('Unknown Repository') }}
332
```