0
# Plugin Integration
1

2
Core MkDocs plugin functionality for seamless integration with MkDocs sites. The plugin system manages configuration, integrates with the MkDocs build process, and coordinates with themes and other plugins.
3

4
## Capabilities
5

6
### MkDocs Plugin
7

8
The main plugin class that integrates mkdocstrings into the MkDocs build pipeline.
9

10
```python { .api }
11
class MkdocstringsPlugin(BasePlugin[PluginConfig]):
12
    """Main MkDocs plugin class for mkdocstrings."""
13
    
14
    def __init__(self) -> None:
15
        """Initialize the plugin."""
16
    
17
    def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
18
        """Process MkDocs configuration and set up mkdocstrings."""
19
    
20
    on_env: CombinedEvent
21
    """Jinja2 environment event handler for template setup."""
22
    
23
    def on_post_build(self, config: MkDocsConfig, **kwargs: Any) -> None:
24
        """Post-build cleanup and finalization."""
25
    
26
    def get_handler(self, handler_name: str) -> BaseHandler:
27
        """Get a handler by name."""
28
    
29
    @property
30
    def handlers(self) -> Handlers:
31
        """Get the handlers instance."""
32
    
33
    @property
34
    def inventory_enabled(self) -> bool:
35
        """Whether inventory is enabled."""
36
    
37
    @property
38
    def plugin_enabled(self) -> bool:
39
        """Whether plugin is enabled."""
40
    
41
    css_filename: str = "assets/_mkdocstrings.css"
42
```
43

44
**Usage Example:**
45

46
```python
47
# In MkDocs plugin context
48
from mkdocstrings import MkdocstringsPlugin
49

50
# Plugin is automatically instantiated by MkDocs
51
plugin = MkdocstringsPlugin()
52

53
# Get a specific handler
54
python_handler = plugin.get_handler("python")
55

56
# Check if inventory is enabled
57
if plugin.inventory_enabled:
58
    # Process inventory
59
    pass
60
```
61

62
### Plugin Configuration
63

64
Configuration schema for the mkdocstrings plugin, defining all available options.
65

66
```python { .api }
67
class PluginConfig(Config):
68
    """Configuration options for mkdocstrings plugin."""
69
    
70
    handlers = opt.Type(dict, default={})
71
    """Global handler configuration dict."""
72
    
73
    default_handler = opt.Type(str, default="python")
74
    """Default handler name to use when none specified."""
75
    
76
    custom_templates = opt.Optional(opt.Dir(exists=True))
77
    """Path to custom templates directory."""
78
    
79
    enable_inventory = opt.Optional(opt.Type(bool))
80
    """Enable/disable inventory creation."""
81
    
82
    enabled = opt.Type(bool, default=True)
83
    """Enable/disable the entire plugin."""
84
    
85
    locale = opt.Optional(opt.Type(str))
86
    """Locale for translations."""
87
```
88

89
**Configuration Examples:**
90

91
Basic configuration in `mkdocs.yml`:
92
```yaml
93
plugins:
94
  - mkdocstrings
95
```
96

97
Advanced configuration:
98
```yaml
99
plugins:
100
  - mkdocstrings:
101
      default_handler: python
102
      enable_inventory: true
103
      locale: en
104
      custom_templates: templates/
105
      handlers:
106
        python:
107
          options:
108
            docstring_style: google
109
            show_source: false
110
            show_root_heading: true
111
        javascript:
112
          options:
113
            show_source: true
114
```
115

116
Multi-language project configuration:
117
```yaml
118
plugins:
119
  - mkdocstrings:
120
      default_handler: python
121
      handlers:
122
        python:
123
          paths: [src]
124
          options:
125
            docstring_style: google
126
            members_order: source
127
            show_signature_annotations: true
128
        javascript:
129
          options:
130
            show_source: false
131
            heading_level: 2
132
```
133

134
## Integration Patterns
135

136
### MkDocs Build Integration
137

138
The plugin integrates with key MkDocs build events:
139

140
1. **Configuration Phase** (`on_config`):
141
   - Validates plugin configuration
142
   - Sets up handlers with their configurations
143
   - Prepares inventory settings
144
   - Configures theme integration
145

146
2. **Post-Build Phase** (`on_post_build`):
147
   - Cleans up temporary resources
148
   - Finalizes inventory files
149
   - Performs handler teardown
150

151
### Theme Integration
152

153
mkdocstrings works with MkDocs themes by:
154

155
- Injecting CSS for styling documentation blocks
156
- Providing theme-specific templates for handlers
157
- Supporting custom template directories
158
- Adapting to theme-specific styling patterns
159

160
### Handler Configuration
161

162
Handlers are configured through the plugin configuration:
163

164
```python
165
# Plugin manages handler lifecycle
166
handlers_config = {
167
    "python": {
168
        "paths": ["src"],
169
        "options": {
170
            "docstring_style": "google",
171
            "show_source": False
172
        }
173
    }
174
}
175

176
# Handlers are instantiated and configured by the plugin
177
handlers = Handlers(
178
    theme=theme_name,
179
    default="python",
180
    handlers_config=handlers_config,
181
    inventory_project=project_name
182
)
183
```
184

185
### Error Handling
186

187
The plugin provides comprehensive error handling:
188

189
- Configuration validation errors
190
- Handler initialization failures
191
- Theme compatibility issues
192
- Template loading problems
193

194
Errors are reported through MkDocs' logging system with clear error messages and suggestions for resolution.