0
# MkDocs Material
1

2
A powerful documentation framework that provides a modern, responsive Material Design theme for MkDocs static site generators. MkDocs Material transforms Markdown documentation into professional static sites with advanced features including full-text search, mobile optimization, syntax highlighting, and support for over 60 languages.
3

4
## Package Information
5

6
- **Package Name**: mkdocs-material
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install mkdocs-material`
10

11
## Core Imports
12

13
MkDocs Material is configured through MkDocs configuration files and doesn't require Python imports for basic usage. The theme and plugins are activated via `mkdocs.yml` configuration.
14

15
## Basic Usage
16

17
### Theme Configuration
18

19
Configure the Material theme in your `mkdocs.yml`:
20

21
```yaml
22
theme:
23
  name: material
24
  features:
25
    - navigation.tabs
26
    - navigation.sections
27
    - navigation.expand
28
    - navigation.top
29
    - search.highlight
30
    - search.share
31
  palette:
32
    - scheme: default
33
      primary: indigo
34
      accent: indigo
35
      toggle:
36
        icon: material/brightness-7
37
        name: Switch to dark mode
38
    - scheme: slate
39
      primary: indigo
40
      accent: indigo
41
      toggle:
42
        icon: material/brightness-4
43
        name: Switch to light mode
44
```
45

46
### Plugin Configuration
47

48
Enable Material plugins in your `mkdocs.yml`:
49

50
```yaml
51
plugins:
52
  - search
53
  - material/search:
54
      lang: en
55
  - material/tags:
56
      tags_file: tags.md
57
  - material/blog:
58
      blog_dir: blog
59
      post_excerpt: required
60
```
61

62
## Architecture
63

64
MkDocs Material extends the MkDocs architecture with:
65

66
- **Theme System**: Jinja2-based templates with Material Design components
67
- **Plugin Framework**: Built-in plugins extending MkDocs functionality
68
- **Asset Pipeline**: TypeScript/JavaScript build system for frontend assets
69
- **Configuration Layer**: YAML-based configuration for theme and plugin options
70

71
The architecture enables complete customization through template overrides, CSS variables, custom plugins, and extensive configuration options while maintaining compatibility with the broader MkDocs ecosystem.
72

73
## Capabilities
74

75
### Theme Configuration
76

77
Complete theme customization including colors, fonts, navigation patterns, and feature toggles. The theme provides dozens of configuration options for visual appearance and user interface behavior.
78

79
```yaml { .api }
80
theme:
81
  name: material
82
  language: en
83
  direction: ltr
84
  features: []
85
  palette: {}
86
  font: {}
87
  icon: {}
88
  logo: string
89
  favicon: string
90
  custom_dir: string
91
```
92

93
[Theme Configuration](./theme-configuration.md)
94

95
### Blog Plugin
96

97
Comprehensive blogging functionality with posts, archives, categories, tags, authors, pagination, and social integration. Transforms MkDocs into a full-featured blog platform.
98

99
```python { .api }
100
class BlogPlugin(BasePlugin[BlogConfig]):
101
    supports_multiple_instances = True
102
    
103
    def on_startup(self, *, command, dirty): ...
104
    def on_config(self, config): ...
105
    @event_priority(-50)
106
    def on_files(self, files, *, config): ...
107
    @event_priority(-50)
108
    def on_nav(self, nav, *, config, files): ...
109
    @event_priority(-50)
110
    def on_page_markdown(self, markdown, *, page, config, files): ...
111
    def on_page_content(self, html, *, page, config, files): ...
112
    def on_env(self, env, *, config, files): ...
113
    @event_priority(-100)
114
    def on_page_context(self, context, *, page, config, nav): ...
115
    def on_shutdown(self): ...
116
```
117

118
[Blog Plugin](./blog-plugin.md)
119

120
### Search Plugin
121

122
Advanced search functionality with language support, search highlighting, search suggestions, and configurable search pipeline. Provides instant client-side search across documentation.
123

124
```python { .api }
125
class SearchPlugin(BasePlugin[SearchConfig]):
126
    def on_startup(self, *, command, dirty): ...
127
    def on_config(self, config): ...
128
    def on_page_context(self, context, *, page, config, nav): ...
129
    def on_post_build(self, *, config): ...
130
    def on_serve(self, server, *, config, builder): ...
131
```
132

133
[Search Plugin](./search-plugin.md)
134

135
### Social Cards Plugin
136

137
Automated social media card generation with customizable layouts, fonts, and branding. Creates Open Graph and Twitter Card images for improved social media sharing.
138

139
```python { .api }
140
class SocialPlugin(BasePlugin[SocialConfig]):
141
    def on_config(self, config): ...
142
    def on_page_content(self, html, page, config, files): ...
143
    def on_post_build(self, config): ...
144
```
145

146
[Social Cards Plugin](./social-plugin.md)
147

148
### Tags Plugin
149

150
Tag-based content organization with automatic tag pages, tag clouds, and tag-based navigation. Enables content discovery through topic-based categorization.
151

152
```python { .api }
153
class TagsPlugin(BasePlugin[TagsConfig]):
154
    supports_multiple_instances = True
155
    
156
    def on_startup(self, *, command, **kwargs) -> None: ...
157
    def on_config(self, config: MkDocsConfig) -> None: ...
158
    @event_priority(-50)
159
    def on_page_markdown(self, markdown: str, *, page: Page, config: MkDocsConfig, **kwargs) -> str: ...
160
    @event_priority(100)
161
    def on_env(self, env: Environment, *, config: MkDocsConfig, **kwargs) -> None: ...
162
    def on_page_context(self, context: TemplateContext, *, page: Page, **kwargs) -> None: ...
163
```
164

165
[Tags Plugin](./tags-plugin.md)
166

167
### Privacy Plugin
168

169
Privacy compliance features including cookie consent, external asset localization, and GDPR compliance helpers. Ensures documentation sites meet privacy regulations.
170

171
```python { .api }
172
class PrivacyPlugin(BasePlugin[PrivacyConfig]):
173
    def on_config(self, config): ...
174
    @event_priority(-100)
175
    def on_files(self, files, *, config): ...
176
    @event_priority(-100)
177
    def on_page_content(self, html, *, page, config, files): ...
178
    def on_env(self, env, *, config, files): ...
179
    @event_priority(-50)
180
    def on_post_template(self, output_content, *, template_name, config): ...
181
    @event_priority(-50)
182
    def on_post_page(self, output, *, page, config): ...
183
    @event_priority(50)
184
    def on_post_build(self, *, config): ...
185
```
186

187
[Privacy Plugin](./privacy-plugin.md)
188

189
### Emoji Extension
190

191
Markdown extension providing emoji and icon rendering with custom icon integration and Material Design icon support.
192

193
```python { .api }
194
# Extension functions
195
def twemoji(options: object, md: Markdown): ...
196
def to_svg(
197
    index: str, shortname: str, alias: str, uc: str | None, alt: str,
198
    title: str, category: str, options: object, md: Markdown
199
): ...
200

201
# Markdown extension configuration
202
markdown_extensions:
203
  - material.extensions.emoji:
204
      emoji_index: !!python/name:material.extensions.emoji.twemoji
205
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
206
      options:
207
        custom_icons:
208
          - overrides/.icons
209
```
210

211
### Additional Plugins
212

213
Meta, Group, Offline, and Info plugins provide specialized functionality for metadata management, plugin grouping, offline support, and environment information gathering.
214

215
```python { .api }
216
class MetaPlugin(BasePlugin[MetaConfig]):
217
    def on_files(self, files, *, config): ...
218
    @event_priority(50)
219
    def on_page_markdown(self, markdown, *, page, config, files): ...
220

221
class GroupPlugin(BasePlugin[GroupConfig]):
222
    supports_multiple_instances = True
223
    
224
    def on_startup(self, *, command, dirty): ...
225
    @event_priority(150)
226
    def on_config(self, config): ...
227

228
class OfflinePlugin(BasePlugin[OfflineConfig]):
229
    def on_config(self, config): ...
230
    @event_priority(-100)
231
    def on_post_build(self, *, config): ...
232

233
class InfoPlugin(BasePlugin[InfoConfig]):
234
    def on_startup(self, *, command, dirty): ...
235
    @event_priority(100)
236
    def on_config(self, config): ...
237
```
238

239
[Additional Plugins](./additional-plugins.md)
240

241
## Types
242

243
```python { .api }
244
from mkdocs.config.defaults import MkDocsConfig
245
from mkdocs.structure.files import Files
246
from mkdocs.structure.nav import Navigation
247
from mkdocs.structure.pages import Page
248
from mkdocs.plugins import BasePlugin, event_priority
249
from jinja2 import Environment, TemplateContext
250
from markdown import Markdown
251
from typing import Dict, Any, Union
252

253
# Theme configuration types
254
ThemeConfig = Dict[str, Any]
255
PaletteConfig = Dict[str, Union[str, Dict[str, str]]]
256
FontConfig = Dict[str, str]
257
IconConfig = Dict[str, str]
258

259
# Plugin configuration types
260
BlogConfig = Dict[str, Any]
261
SearchConfig = Dict[str, Any]
262
SocialConfig = Dict[str, Any]
263
TagsConfig = Dict[str, Any]
264
PrivacyConfig = Dict[str, Any]
265
MetaConfig = Dict[str, Any]
266
GroupConfig = Dict[str, Any]
267
OfflineConfig = Dict[str, Any]
268
InfoConfig = Dict[str, Any]
269
```