0
# Plugin Configuration
1

2
Configuration options for controlling plugin behavior, template rendering, Jinja2 settings, and module loading. These settings are defined in the mkdocs.yml file under the macros plugin section.
3

4
## Capabilities
5

6
### Basic Configuration
7

8
Core configuration options for module loading and rendering behavior.
9

10
```python { .api }
11
# In mkdocs.yml under plugins: - macros:
12
module_name: str = 'main'          # Python module filename for macros
13
modules: list = []                 # List of pre-installed modules (pluglets)  
14
render_by_default: bool = True     # Render pages by default vs opt-in
15
verbose: bool = False              # Enable verbose logging
16
```
17

18
#### Usage Examples
19

20
Basic configuration:
21
```yaml
22
plugins:
23
  - macros:
24
      module_name: custom_macros
25
      verbose: true
26
```
27

28
With multiple pluglets:
29
```yaml
30
plugins:
31
  - macros:
32
      modules:
33
        - mkdocs-macros-test
34
        - custom-pluglet:my_module
35
      render_by_default: false
36
```
37

38
### Path and File Configuration
39

40
Options for controlling which files are rendered and where template includes are located.
41

42
```python { .api }
43
force_render_paths: str = ''       # Pathspec patterns to force rendering
44
include_dir: str = ''              # Directory for {% include %} and {% import %} files
45
include_yaml: list = []            # Additional YAML files to load
46
```
47

48
#### Usage Examples
49

50
Force rendering specific paths:
51
```yaml
52
plugins:
53
  - macros:
54
      force_render_paths: |
55
        docs/generated/**
56
        api/*.md
57
        !docs/static/**
58
```
59

60
Include configuration:
61
```yaml
62
plugins:
63
  - macros:
64
      include_dir: templates
65
      include_yaml:
66
        - data/constants.yml
67
        - config/variables.yml
68
        - nested_key: data/nested.yml
69
```
70

71
### Jinja2 Template Configuration
72

73
Custom Jinja2 template markers for avoiding conflicts with other systems.
74

75
```python { .api }
76
j2_block_start_string: str = ''    # Custom Jinja2 block start marker (default: {%)
77
j2_block_end_string: str = ''      # Custom Jinja2 block end marker (default: %})
78
j2_variable_start_string: str = '' # Custom Jinja2 variable start marker (default: {{)
79
j2_variable_end_string: str = ''   # Custom Jinja2 variable end marker (default: }})
80
j2_comment_start_string: str = ''  # Custom Jinja2 comment start marker (default: {#)
81
j2_comment_end_string: str = ''    # Custom Jinja2 comment end marker (default: #})
82
```
83

84
#### Usage Examples
85

86
Custom markers to avoid conflicts:
87
```yaml
88
plugins:
89
  - macros:
90
      j2_variable_start_string: '<<'
91
      j2_variable_end_string: '>>'
92
      j2_block_start_string: '<<%'
93
      j2_block_end_string: '%>>'
94
```
95

96
With custom markers, use:
97
```markdown
98
Project name: << config.site_name >>
99

100
<<% if environment.system == 'Darwin' %>>
101
Running on macOS
102
<<% endif %>>
103
```
104

105
### Error Handling Configuration
106

107
Options for controlling behavior when template rendering encounters errors or undefined variables.
108

109
```python { .api }
110
on_undefined: str = 'keep'         # Behavior for undefined variables: 'keep', 'silent', 'strict', 'lax'
111
on_error_fail: bool = False        # Exit on rendering errors in CI/CD
112
```
113

114
#### Undefined Variable Behaviors
115

116
- `'keep'` (default): Leave undefined variables as-is in output
117
- `'silent'`: Replace undefined variables with empty string
118
- `'strict'`: Raise exception on undefined variables
119
- `'lax'`: Pass any unknown objects as empty string
120

121
#### Usage Examples
122

123
Strict mode for development:
124
```yaml
125
plugins:
126
  - macros:
127
      on_undefined: strict
128
      on_error_fail: true
129
```
130

131
Production-safe configuration:
132
```yaml
133
plugins:
134
  - macros:
135
      on_undefined: silent
136
      on_error_fail: false
137
```
138

139
## Complete Configuration Example
140

141
```yaml
142
plugins:
143
  - macros:
144
      # Module configuration
145
      module_name: project_macros
146
      modules:
147
        - mkdocs-macros-test
148
        - company-pluglet:shared_macros
149
      
150
      # Rendering configuration
151
      render_by_default: true
152
      force_render_paths: |
153
        docs/api/**
154
        docs/generated/*.md
155
        !docs/static/**
156
      
157
      # Template includes
158
      include_dir: templates
159
      include_yaml:
160
        - data/project_vars.yml
161
        - constants: config/constants.yml
162
      
163
      # Custom Jinja2 markers (if needed)
164
      j2_variable_start_string: '[['
165
      j2_variable_end_string: ']]'
166
      
167
      # Error handling
168
      on_undefined: keep
169
      on_error_fail: false
170
      verbose: true
171
```
172

173
## Page-Level Control
174

175
Individual pages can override rendering behavior using YAML front matter:
176

177
```markdown
178
---
179
render_macros: true   # Force rendering even if render_by_default is false
180
render_macros: false  # Skip rendering even if render_by_default is true
181
---
182

183
# Page content here
184
```