0
# Additional Plugins
1

2
Specialized plugins providing metadata management, plugin grouping, offline support, and environment information gathering. These utility plugins extend MkDocs Material's functionality for specific use cases and development workflows.
3

4
## Capabilities
5

6
### Meta Plugin
7

8
Metadata management plugin for processing and injecting metadata across documentation pages.
9

10
```yaml { .api }
11
plugins:
12
  - material/meta:
13
      enabled: true              # Enable meta plugin (default: true)
14
      meta_file: "**/.meta.yml"  # Metadata file pattern
15
```
16

17
#### Meta Plugin Configuration
18

19
```yaml { .api }
20
plugins:
21
  - material/meta:
22
      meta_file: "**/.meta.yml"        # Metadata file pattern
23
      meta_file_recursive: true        # Recursive metadata inheritance
24
      meta_file_inherit: true          # Inherit parent metadata
25
```
26

27
#### Metadata File Structure
28

29
```yaml
30
# .meta.yml
31
title: Section Title
32
description: Section description
33
authors:
34
  - John Doe
35
  - Jane Smith
36
tags:
37
  - documentation
38
  - api
39
template: custom.html
40
```
41

42
### Group Plugin
43

44
Plugin grouping and organization functionality for managing complex plugin configurations.
45

46
```yaml { .api }
47
plugins:
48
  - material/group:
49
      enabled: true              # Enable group plugin (default: true)
50
      plugins: []               # Plugin group configuration
51
```
52

53
#### Group Plugin Configuration
54

55
```yaml { .api }
56
plugins:
57
  - material/group:
58
      plugins:
59
        - group: development
60
          plugins:
61
            - material/info
62
            - material/meta
63
        - group: production
64
          plugins:
65
            - material/privacy
66
            - material/social
67
```
68

69
### Offline Plugin
70

71
Offline support functionality for creating documentation that works without internet connectivity.
72

73
```yaml { .api }
74
plugins:
75
  - material/offline:
76
      enabled: true              # Enable offline support (default: true)
77
```
78

79
#### Offline Plugin Features
80

81
- Service worker generation
82
- Asset caching strategies
83
- Offline-first navigation
84
- Progressive web app capabilities
85

86
### Info Plugin
87

88
Environment and build information gathering for debugging and development workflows.
89

90
```yaml { .api }
91
plugins:
92
  - material/info:
93
      enabled: true                    # Enable info plugin (default: true)
94
      archive: true                   # Create info archive (default: true)
95
      archive_stop_on_violation: true  # Stop on policy violations
96
```
97

98
#### Info Plugin Configuration
99

100
```yaml { .api }
101
plugins:
102
  - material/info:
103
      archive: true                   # Generate info archive
104
      archive_format: zip             # Archive format (zip/tar)
105
      archive_name: site-info         # Archive filename
106
      archive_stop_on_violation: false  # Continue on violations
107
```
108

109
## Usage Examples
110

111
### Meta Plugin Usage
112

113
#### Directory Structure
114
```
115
docs/
116
├── .meta.yml                 # Root metadata
117
├── api/
118
│   ├── .meta.yml            # API section metadata
119
│   ├── authentication.md
120
│   └── endpoints.md
121
└── guides/
122
    ├── .meta.yml            # Guides section metadata
123
    └── getting-started.md
124
```
125

126
#### Root Metadata (.meta.yml)
127
```yaml
128
authors:
129
  - Technical Writing Team
130
tags:
131
  - documentation
132
template: base.html
133
```
134

135
#### Section Metadata (api/.meta.yml)
136
```yaml
137
title: API Documentation
138
description: Complete API reference and guides
139
tags:
140
  - api
141
  - reference
142
template: api.html
143
```
144

145
### Group Plugin Usage
146

147
#### Development Configuration
148
```yaml
149
plugins:
150
  - material/group:
151
      plugins:
152
        - group: core
153
          plugins:
154
            - search
155
            - material/search
156
        - group: content
157
          plugins:
158
            - material/blog
159
            - material/tags
160
        - group: development
161
          enabled: !ENV [DEBUG, false]
162
          plugins:
163
            - material/info
164
```
165

166
### Offline Plugin Usage
167

168
#### Basic Offline Support
169
```yaml
170
plugins:
171
  - material/offline
172

173
theme:
174
  name: material
175
  features:
176
    - content.code.copy
177
    - navigation.instant  # Works with offline plugin
178
```
179

180
#### Advanced Offline Configuration
181
```yaml
182
plugins:
183
  - material/offline
184

185
extra:
186
  manifest: manifest.json  # PWA manifest
187
  
188
theme:
189
  name: material
190
  features:
191
    - navigation.instant
192
    - navigation.tracking
193
```
194

195
### Info Plugin Usage
196

197
#### Development Info Gathering
198
```yaml
199
plugins:
200
  - material/info:
201
      archive: true
202
      archive_name: debug-info
203
      archive_stop_on_violation: false
204
```
205

206
#### Production Info Monitoring
207
```yaml
208
plugins:
209
  - material/info:
210
      archive: false  # Don't create archives in production
211
```
212

213
## Plugin APIs
214

215
### Meta Plugin API
216

217
```python { .api }
218
class MetaPlugin(BasePlugin[MetaConfig]):
219
    """Meta plugin for metadata management."""
220
    
221
    def on_files(self, files, *, config):
222
        """Process metadata files."""
223
    
224
    @event_priority(50)
225
    def on_page_markdown(self, markdown, *, page, config, files):
226
        """Inject metadata into page markdown."""
227
```
228

229
### Group Plugin API
230

231
```python { .api }
232
class GroupPlugin(BasePlugin[GroupConfig]):
233
    """Group plugin for plugin organization."""
234
    
235
    supports_multiple_instances = True
236
    
237
    def on_startup(self, *, command, dirty):
238
        """Initialize plugin groups."""
239
    
240
    @event_priority(150)
241
    def on_config(self, config):
242
        """Configure plugin groups."""
243
```
244

245
### Offline Plugin API
246

247
```python { .api }
248
class OfflinePlugin(BasePlugin[OfflineConfig]):
249
    """Offline plugin for progressive web app functionality."""
250
    
251
    def on_config(self, config):
252
        """Configure offline functionality."""
253
    
254
    @event_priority(-100)
255
    def on_post_build(self, *, config):
256
        """Generate service worker and offline assets."""
257
```
258

259
### Info Plugin API
260

261
```python { .api }
262
class InfoPlugin(BasePlugin[InfoConfig]):
263
    """Info plugin for environment information gathering."""
264
    
265
    def on_startup(self, *, command, dirty):
266
        """Gather startup information."""
267
    
268
    @event_priority(100)
269
    def on_config(self, config):
270
        """Configure info collection."""
271
```
272

273
## Configuration Schemas
274

275
### Meta Plugin Schema
276

277
```python { .api }
278
class MetaConfig(Config):
279
    """Configuration options for the meta plugin."""
280
    
281
    enabled = Type(bool, default=True)
282
    meta_file = Type(str, default="**/.meta.yml")
283
    meta_file_recursive = Type(bool, default=True)
284
    meta_file_inherit = Type(bool, default=True)
285
```
286

287
### Group Plugin Schema
288

289
```python { .api }
290
class GroupConfig(Config):
291
    """Configuration options for the group plugin."""
292
    
293
    enabled = Type(bool, default=True)
294
    plugins = Type(list, default=[])
295
```
296

297
### Offline Plugin Schema
298

299
```python { .api }
300
class OfflineConfig(Config):
301
    """Configuration options for the offline plugin."""
302
    
303
    enabled = Type(bool, default=True)
304
```
305

306
### Info Plugin Schema
307

308
```python { .api }
309
class InfoConfig(Config):
310
    """Configuration options for the info plugin."""
311
    
312
    enabled = Type(bool, default=True)
313
    archive = Type(bool, default=True)
314
    archive_format = Choice(['zip', 'tar'], default='zip')
315
    archive_name = Type(str, default='site-info')
316
    archive_stop_on_violation = Type(bool, default=True)
317
```
318

319
## Integration Examples
320

321
### Complete Plugin Stack
322

323
```yaml
324
plugins:
325
  # Core functionality
326
  - search
327
  - material/search:
328
      lang: en
329
  
330
  # Content management
331
  - material/meta:
332
      meta_file: "**/.meta.yml"
333
  - material/tags:
334
      tags_file: tags.md
335
  - material/blog:
336
      blog_dir: blog
337
  
338
  # Privacy and social
339
  - material/privacy:
340
      external_assets: bundle
341
  - material/social:
342
      cards_layout_options:
343
        background_color: "#1976D2"
344
  
345
  # Utility plugins
346
  - material/group:
347
      plugins:
348
        - group: development
349
          enabled: !ENV [DEBUG, false]
350
          plugins:
351
            - material/info
352
  - material/offline
353
```
354

355
### Conditional Plugin Loading
356

357
```yaml
358
plugins:
359
  - material/group:
360
      plugins:
361
        - group: production
362
          enabled: !ENV [PRODUCTION, false]
363
          plugins:
364
            - material/privacy
365
            - material/social
366
            - material/offline
367
        - group: development
368
          enabled: !ENV [DEBUG, false]
369
          plugins:
370
            - material/info:
371
                archive: true
372
```