1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
---
date: 2023-10-07
authors: [HsiangNianian]
description: >
Rule 基类已经支持泛型了。
categories:
- Rules
links:
- standard/what-is-rule-package
---
# Rule 基类已经支持泛型了
__Hey there! You're looking at our new blog, built with the brand new
[built-in blog plugin]. With this plugin, you can easily build a blog alongside
your documentation or standalone.__
Proper support for blogging, as requested by many users over the past few years,
was something that was desperately missing from Material for MkDocs' feature set.
While everybody agreed that blogging support was a blind spot, it was not
obvious whether MkDocs could be extended in a way to allow for blogging as we
know it from [Jekyll] and friends. The [built-in blog plugin] proves that it is,
after all, possible to build a blogging engine on top of MkDocs, in order to
create a technical blog alongside your documentation, or as the main thing.
<!-- more -->
_This article explains how to build a standalone blog with Material for MkDocs.
If you want to build a blog alongside your documentation, please refer to
[the plugin's documentation][built-in blog plugin]._
[built-in blog plugin]: ../../plugins/blog.md
[Jekyll]: https://jekyllrb.com/
## Quick start
### Creating a standalone blog
You can bootstrap a new project using the `mkdocs` executable:
```
mkdocs new .
```
This will create the following structure:
``` { .sh .no-copy }
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
```
#### Configuration
In this article, we're going to build a standalone blog, which means that the
blog lives at the root of your project. For this reason, open `mkdocs.yml`,
and replace its contents with:
``` yaml
site_name: My Blog
theme:
name: material
features:
- navigation.sections
plugins:
- blog:
blog_dir: . # (1)!
- search
- tags
nav:
- index.md
```
1. This is the important part – we're hosting the blog at the root of the
project, and not in a subdirectory. For more information, see the
[`blog_dir`][blog_dir] configuration option.
[blog_dir]: ../../setup/setting-up-a-blog.md#+blog.blog_dir
#### Blog setup
The blog index page lives in `docs/index.md`. This page was pre-filled by
MkDocs with some content, so we're going to replace it with what we need to
bootstrap the blog:
``` markdown
# Blog
```
That's it.
### Writing your first post
Now that we have set up the [built-in blog plugin], we can start writing our
first post. All blog posts are written with the [exact same Markdown flavor] as
already included with Material for MkDocs. First, create a folder called `posts`
with a file called `hello-world.md`:
``` { .sh .no-copy }
.
├─ docs/
│ ├─ posts/
│ │ └─ hello-world.md # (1)!
│ └─ index.md
└─ mkdocs.yml
```
1. If you'd like to arrange posts differently, you're free to do so. The URLs
are built from the format specified in [`post_url_format`][post slugs] and
the titles and dates of posts, no matter how they are organized
inside the `posts` directory.
Then, open up `hello-world.md`, and add the following lines:
``` yaml
---
draft: true # (1)!
date: 2022-01-31
categories:
- Hello
- World
---
# Hello world!
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec
maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula
erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst.
Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris
Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in
sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac
metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet.
<!-- more -->
Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum
massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam
tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet
molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus.
Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat.
In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc
pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis
arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue.
In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque
tellus id elit ultricies, vel finibus erat cursus.
```
1. If you mark a post as a [draft], a red marker appears next to the post date
on index pages. When the site is built, drafts are not included in the
output. [This behavior can be changed], e.g. for rendering drafts when
building deploy previews.
When you spin up the [live preview server], you should be greeted by your first
post! You'll also realize, that [archive] and [category] indexes have been
automatically generated for you:
![Blog]
However, this is just the start. The [built-in blog plugin] packs a lot of
functionality needed in day-to-day blogging. Visit the documentation of the
plugin to learn about the following topics:
<div class="mdx-columns" markdown>
- [Adding an excerpt]
- [Adding authors]
- [Adding categories]
- [Adding tags]
- [Adding related links]
- [Linking from and to posts]
- [Setting the reading time]
- [Setting defaults]
</div>
Additionally, the [built-in blog plugin] has dozens of [configuration options]
which allow for fine-tuning the output. You can configure post slugs, general
behavior and much more.
[exact same Markdown flavor]: ../../reference/index.md
[post slugs]: ../../setup/setting-up-a-blog.md#+blog.post_url_format
[draft]: ../../setup/setting-up-a-blog.md#drafts
[This behavior can be changed]: ../../setup/setting-up-a-blog.md#+blog.draft
[live preview server]: ../../creating-your-site.md#previewing-as-you-write
[archive]: ../../setup/setting-up-a-blog.md#archive
[category]: ../../setup/setting-up-a-blog.md#categories
[Blog]: blog-support-just-landed/blog.png
[Blog post]: blog-support-just-landed/blog-post.png
[Adding an excerpt]: ../../setup/setting-up-a-blog.md#adding-an-excerpt
[Adding authors]: ../../setup/setting-up-a-blog.md#adding-authors
[Adding categories]: ../../setup/setting-up-a-blog.md#adding-categories
[Adding tags]: ../../setup/setting-up-a-blog.md#adding-tags
[Adding related links]: ../../setup/setting-up-a-blog.md#adding-related-links
[Linking from and to posts]: ../../setup/setting-up-a-blog.md#linking-from-and-to-posts
[Setting the reading time]: ../../setup/setting-up-a-blog.md#setting-the-reading-time
[Setting defaults]: ../../setup/setting-up-a-blog.md#setting-defaults
[configuration options]: ../../setup/setting-up-a-blog.md#configuration
## What's next?
Getting basic blogging support out the door was quite a challenge – the
[built-in blog plugin] is probably the biggest release this year and already
packs a lot of functionality. However, Material for MkDocs is used in many
different contexts, which is why we'd expect to iterate, as always.
Some ideas already proposed by users:
- __Blog series__: Authors should be able to create so called blog series and
assign posts to a blog series using simple identifiers. For each post that is
part of a series, a list with links to all other posts should be included in
the post's content.
- __Author indexes__: Besides [archive] and [category] indexes, authors should
be able to create per-author indexes, which list all posts linked to an
author. Additionally, a profile should be created for each author and linked
from posts.
- __Social share buttons__: It should be easy to share blog posts via social
media or other ways. For this reason, it should be possible to automatically
include social sharing buttons with each post.
What's still missing from the brand new [built-in blog plugin]? Feel free to
share your ideas in the comments. Together, we can build one of the best modern
engines for technical blogging!
|