0
# Built-in Functions
1

2
Default macros and filters provided by the plugin for common templating tasks, documentation generation, and utility functions.
3

4
## Capabilities
5

6
### Documentation Macros
7

8
Built-in macros for generating documentation and debugging template environments.
9

10
```python { .api }
11
def context(obj: dict = None) -> list:
12
    """
13
    List variables and their types/values for documentation.
14
    
15
    Args:
16
        obj: Object to inspect (defaults to all template variables)
17
        
18
    Returns:
19
        List of (name, type, formatted_value) tuples
20
    """
21

22
def macros_info() -> str:
23
    """
24
    Generate comprehensive documentation of the plugin environment.
25
    
26
    Returns:
27
        HTML documentation showing all variables, macros, and filters
28
    """
29
```
30

31
#### Usage Examples
32

33
Variable inspection:
34
```markdown
35
## Available Variables
36

37
{{ context() | pretty }}
38

39
## Page Variables Only
40

41
{{ context(page) | pretty }}
42

43
## Configuration Variables
44

45
{{ context(config) | pretty }}
46
```
47

48
Complete environment documentation:
49
```markdown
50
{{ macros_info() }}
51
```
52

53
Custom object inspection:
54
```markdown
55
{% set my_data = {'name': 'John', 'age': 30} %}
56

57
{{ context(my_data) | pretty }}
58
```
59

60
### Time and Date Macros
61

62
Built-in macros for working with dates and timestamps.
63

64
```python { .api }
65
def now() -> datetime:
66
    """
67
    Get current datetime at build time.
68
    
69
    Returns:
70
        datetime object representing build time
71
    """
72
```
73

74
#### Usage Examples
75

76
Current timestamp:
77
```markdown
78
Built on {{ now() }}
79

80
Copyright {{ now().year }} My Company
81
```
82

83
Formatted dates:
84
```markdown
85
Last updated: {{ now().strftime('%Y-%m-%d %H:%M:%S') }}
86

87
Today is {{ now().strftime('%A, %B %d, %Y') }}
88
```
89

90
Date arithmetic:
91
```markdown
92
{% set build_date = now() %}
93
{% set days_in_year = 365 %}
94

95
This documentation was built on day {{ build_date.timetuple().tm_yday }} of {{ build_date.year }}.
96
```
97

98
### URL Utilities
99

100
Built-in macros for handling URLs and relative links.
101

102
```python { .api }
103
def fix_url(url: str) -> str:
104
    """
105
    Convert relative URLs to point to docs directory.
106
    
107
    Args:
108
        url: URL to fix (relative or absolute)
109
        
110
    Returns:
111
        Fixed URL that points to correct location
112
    """
113
```
114

115
#### Usage Examples
116

117
Image links:
118
```markdown
119
![Logo]({{ fix_url('images/logo.png') }})
120

121
[Download]({{ fix_url('assets/manual.pdf') }})
122
```
123

124
Dynamic URLs:
125
```markdown
126
{% set image_path = 'screenshots/' + page.title.lower() + '.png' %}
127
![Screenshot]({{ fix_url(image_path) }})
128
```
129

130
### Documentation Filters
131

132
Built-in filters for formatting and presenting template data.
133

134
```python { .api }
135
def pretty(var_list: list) -> str:
136
    """
137
    Format output from context() macro as HTML table.
138
    
139
    Args:
140
        var_list: List of (name, type, content) tuples from context()
141
        
142
    Returns:
143
        HTML table with formatted variable information
144
    """
145
```
146

147
#### Usage Examples
148

149
Variable documentation:
150
```markdown
151
## Template Variables
152

153
{{ context() | pretty }}
154

155
## Git Information
156

157
{{ context(git) | pretty }}
158
```
159

160
Custom object formatting:
161
```markdown
162
{% set project_info = {
163
    'name': config.site_name,
164
    'version': version,
165
    'author': author
166
} %}
167

168
{{ context(project_info) | pretty }}
169
```
170

171
### URL Filters
172

173
Built-in filters for URL manipulation and path handling.
174

175
```python { .api }
176
def relative_url(path: str) -> str:
177
    """
178
    Convert path to URL relative to current page.
179
    
180
    Args:
181
        path: Page path to convert
182
        
183
    Returns:
184
        URL relative to current page
185
    """
186
```
187

188
#### Usage Examples
189

190
Navigation links:
191
```markdown
192
[Home]({{ 'index.md' | relative_url }})
193

194
[API Reference]({{ 'api/index.md' | relative_url }})
195
```
196

197
Dynamic navigation:
198
```markdown
199
{% for nav_page in navigation.pages %}
200
- [{{ nav_page.title }}]({{ nav_page.url | relative_url }})
201
{% endfor %}
202
```
203

204
Cross-references:
205
```markdown
206
See also: [{{ page.title }}]({{ page.url | relative_url }})
207
```
208

209
## Combined Usage Patterns
210

211
### Dynamic Documentation Generation
212

213
```markdown
214
# {{ config.site_name }} Documentation
215

216
Generated on {{ now().strftime('%Y-%m-%d') }} from commit {{ git.short_commit }}.
217

218
## Project Information
219

220
{{ context({
221
    'Site': config.site_name,
222
    'Version': version,
223
    'Python': environment.python_version,
224
    'MkDocs': environment.mkdocs_version
225
}) | pretty }}
226

227
## Available Macros
228

229
{{ context(macros) | pretty }}
230
```
231

232
### Environment-Specific Content
233

234
```markdown
235
{% set env_info = {
236
    'Build System': environment.system,
237
    'Build Time': now(),
238
    'Git Branch': git.tag or 'main',
239
    'Debug Mode': plugin.verbose
240
} %}
241

242
## Build Information
243

244
{{ context(env_info) | pretty }}
245

246
{% if plugin.verbose %}
247
## Debug Information
248

249
{{ macros_info() }}
250
{% endif %}
251
```
252

253
### Asset Management
254

255
```markdown
256
{% set assets = {
257
    'logo': fix_url('images/logo.svg'),
258
    'stylesheet': fix_url('css/custom.css'),
259
    'script': fix_url('js/app.js')
260
} %}
261

262
<link rel="stylesheet" href="{{ assets.stylesheet }}">
263
<script src="{{ assets.script }}"></script>
264

265
![Company Logo]({{ assets.logo }})
266
```
267

268
### Navigation Generation
269

270
```markdown
271
## Quick Navigation
272

273
{% for section in navigation.items %}
274
{% if section.is_section %}
275
### {{ section.title }}
276
{% for page in section.children %}
277
- [{{ page.title }}]({{ page.url | relative_url }})
278
{% endfor %}
279
{% endif %}
280
{% endfor %}
281

282
---
283
*Generated {{ now().strftime('%B %d, %Y') }}*
284
```
285

286
## Error Handling
287

288
Built-in functions include error handling for common issues:
289

290
```markdown
291
<!-- Safe git access -->
292
{% if git.status %}
293
Last commit: {{ git.short_commit }}
294
{% else %}
295
Not a git repository
296
{% endif %}
297

298
<!-- Safe URL handling -->
299
{{ fix_url('path/that/might/not/exist.png') }}
300

301
<!-- Safe context inspection -->
302
{{ context(undefined_variable) | pretty }}
303
```
304

305
## Function Availability
306

307
All built-in functions are automatically available in templates without imports:
308

309
- Available in all markdown files
310
- Available in included templates
311
- Available in macro definitions
312
- Can be overridden by custom functions with same names
313

314
## Performance Considerations
315

316
- `now()` returns the same datetime object throughout the build
317
- `context()` and `macros_info()` generate HTML on each call
318
- `fix_url()` performs path manipulation on each call
319
- Use `{% set %}` to cache results of expensive operations:
320

321
```markdown
322
{% set build_time = now() %}
323
{% set project_vars = context() %}
324

325
Built: {{ build_time }}
326
Variables: {{ project_vars | pretty }}
327
```