0
# Blog Plugin
1
2
Comprehensive blogging functionality that transforms MkDocs into a full-featured blog platform. The blog plugin provides posts, archives, categories, tags, authors, pagination, reading time estimation, and social integration.
3
4
## Capabilities
5
6
### Basic Blog Setup
7
8
Core blog configuration that establishes the blog structure and basic functionality.
9
10
```yaml { .api }
11
plugins:
12
- material/blog:
13
enabled: true # Enable blog plugin (default: true)
14
blog_dir: blog # Blog directory (default: blog)
15
blog_toc: false # Show TOC for blog pages (default: false)
16
```
17
18
### Post Configuration
19
20
Comprehensive post handling including URL structure, date formatting, and content processing.
21
22
```yaml { .api }
23
plugins:
24
- material/blog:
25
# Post directory and structure
26
post_dir: "{blog}/posts" # Posts directory pattern
27
post_url_format: "{date}/{slug}" # Post URL structure
28
post_url_date_format: "yyyy/MM/dd" # Date format in URLs
29
post_date_format: "long" # Display date format
30
31
# Post processing
32
post_slugify: !!python/name:pymdownx.slugs.slugify
33
post_slugify_separator: "-" # Slug separator
34
post_excerpt: "optional" # Excerpt requirement (optional/required)
35
post_excerpt_separator: "<!-- more -->" # Excerpt separator
36
post_excerpt_max_authors: 1 # Max authors in excerpt
37
post_excerpt_max_categories: 5 # Max categories in excerpt
38
39
# Reading time
40
post_readtime: true # Show reading time (default: true)
41
post_readtime_words_per_minute: 265 # Reading speed calculation
42
```
43
44
### Archive Configuration
45
46
Automatic archive generation with date-based organization and navigation.
47
48
```yaml { .api }
49
plugins:
50
- material/blog:
51
# Archive settings
52
archive: true # Enable archive (default: true)
53
archive_name: "blog.archive" # Archive page name
54
archive_date_format: "yyyy" # Archive date display format
55
archive_url_date_format: "yyyy" # Archive URL date format
56
archive_url_format: "archive/{date}" # Archive URL structure
57
archive_toc: false # Archive page TOC
58
```
59
60
### Category Configuration
61
62
Category-based content organization with automatic category pages and navigation.
63
64
```yaml { .api }
65
plugins:
66
- material/blog:
67
# Category settings
68
categories: true # Enable categories (default: true)
69
categories_name: "blog.categories" # Categories page name
70
categories_url_format: "category/{slug}" # Category URL structure
71
categories_slugify: !!python/name:pymdownx.slugs.slugify
72
categories_slugify_separator: "-" # Category slug separator
73
categories_allowed: [] # Allowed categories list
74
categories_toc: false # Category page TOC
75
```
76
77
### Pagination Configuration
78
79
Paginated blog views with configurable page sizes and navigation.
80
81
```yaml { .api }
82
plugins:
83
- material/blog:
84
# Pagination settings
85
pagination: true # Enable pagination (default: true)
86
pagination_per_page: 10 # Posts per page
87
pagination_url_format: "page/{page}" # Pagination URL structure
88
pagination_format: "$link_first $link_previous ~2~ $link_next $link_last"
89
pagination_keep_content: false # Keep content on paginated pages
90
```
91
92
### Authors Configuration
93
94
Author management with profiles, social links, and author pages.
95
96
```yaml { .api }
97
plugins:
98
- material/blog:
99
# Authors settings
100
authors: true # Enable authors (default: true)
101
authors_file: "{blog}/.authors.yml" # Authors configuration file
102
authors_profiles: true # Enable author profiles
103
authors_profiles_name: "blog.authors" # Authors page name
104
authors_profiles_url_format: "author/{slug}" # Author URL structure
105
authors_profiles_toc: false # Author page TOC
106
```
107
108
### Draft and Visibility
109
110
Content visibility control including drafts and publication management.
111
112
```yaml { .api }
113
plugins:
114
- material/blog:
115
# Draft settings
116
draft: false # Include drafts (default: false)
117
draft_on_serve: true # Show drafts during serve
118
draft_if_future_date: false # Draft posts with future dates
119
```
120
121
## Usage Examples
122
123
### Basic Blog Setup
124
125
```yaml
126
plugins:
127
- material/blog:
128
blog_dir: blog
129
post_excerpt: required
130
categories: true
131
archive: true
132
```
133
134
### Advanced Blog Configuration
135
136
```yaml
137
plugins:
138
- material/blog:
139
# Blog structure
140
blog_dir: articles
141
post_dir: "{blog}/posts"
142
post_url_format: "{categories[0]}/{date}/{slug}"
143
post_url_date_format: "yyyy/MM/dd"
144
145
# Content processing
146
post_excerpt: required
147
post_excerpt_separator: "<!-- more -->"
148
post_readtime: true
149
post_readtime_words_per_minute: 250
150
151
# Organization
152
categories: true
153
categories_allowed:
154
- Technology
155
- Documentation
156
- Tutorials
157
archive: true
158
archive_date_format: "MMMM yyyy"
159
160
# Pagination
161
pagination: true
162
pagination_per_page: 5
163
164
# Authors
165
authors: true
166
authors_file: "{blog}/.authors.yml"
167
authors_profiles: true
168
```
169
170
### Author Configuration File
171
172
Create `.authors.yml` in your blog directory:
173
174
```yaml
175
authors:
176
john:
177
name: John Doe
178
description: Technical Writer
179
avatar: https://example.com/avatar.jpg
180
url: https://johndoe.com
181
social:
182
- icon: fontawesome/brands/github
183
link: https://github.com/johndoe
184
- icon: fontawesome/brands/twitter
185
link: https://twitter.com/johndoe
186
187
jane:
188
name: Jane Smith
189
description: Software Engineer
190
avatar: https://example.com/jane.jpg
191
```
192
193
### Blog Post Format
194
195
Create posts in your `posts` directory with proper frontmatter:
196
197
```markdown
198
---
199
title: My Blog Post
200
description: A short description of the post
201
authors:
202
- john
203
- jane
204
categories:
205
- Technology
206
- Tutorials
207
date: 2023-12-01
208
draft: false
209
---
210
211
# My Blog Post
212
213
This is the post content.
214
215
<!-- more -->
216
217
This content appears after the excerpt separator.
218
```
219
220
### Minimal Blog
221
222
```yaml
223
plugins:
224
- material/blog
225
```
226
227
## Plugin API
228
229
```python { .api }
230
class BlogPlugin(BasePlugin[BlogConfig]):
231
"""Blog plugin for creating blog functionality in MkDocs Material."""
232
supports_multiple_instances = True
233
234
def on_startup(self, *, command, dirty):
235
"""Determine whether we're serving the site."""
236
237
def on_config(self, config):
238
"""Initialize authors and set defaults."""
239
240
@event_priority(-50)
241
def on_files(self, files, *, config):
242
"""Resolve and load posts and generate views (run later)."""
243
244
@event_priority(-50)
245
def on_nav(self, nav, *, config, files):
246
"""Attach posts and views to navigation (run later)."""
247
248
@event_priority(-50)
249
def on_page_markdown(self, markdown, *, page, config, files):
250
"""Prepare post for rendering (run later)."""
251
252
def on_page_content(self, html, *, page, config, files):
253
"""Process posts."""
254
255
def on_env(self, env, *, config, files):
256
"""Register template filters for plugin."""
257
258
@event_priority(-100)
259
def on_page_context(self, context, *, page, config, nav):
260
"""Prepare view for rendering (run latest)."""
261
262
def on_shutdown(self):
263
"""Remove temporary directory on shutdown."""
264
```