博客支持刚刚发布

¥Blog support just landed

嘿！您正在浏览我们全新的博客，它使用全新的内置博客插件构建。使用此插件，您可以轻松创建博客，与文档同步，或独立运行。

¥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.

正如过去几年许多用户所期望的那样，Material 中对博客的支持是 MkDocs 功能集中亟待解决的问题。虽然大家都认为博客支持是一个盲点，但 MkDocs 能否扩展以实现我们熟知的Jekyll及其同类产品中的博客功能尚不明确。内置的博客插件证明了，在 MkDocs 之上构建博客引擎是可行的，这样就可以在文档之外创建技术博客，或者将其作为主要内容。

¥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.

本文介绍如何使用 Material for MkDocs 构建独立博客。如果您想在文档之外构建博客，请参阅该插件的文档。

¥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.

快速启动

¥Quick start

创建独立博客

¥Creating a standalone blog

您可以使用mkdocs可执行文件引导一个新项目：

¥You can bootstrap a new project using the mkdocs executable:

mkdocs new .

这将创建以下结构：

¥This will create the following structure:

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

配置

¥Configuration

在本文中，我们将构建一个独立博客，这意味着该博客位于项目的根目录下。为此，请打开mkdocs.yml ，并将其内容替换为：

¥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:

site_name: My Blog
theme:
  name: material
  features:
    - navigation.sections
plugins:
  - blog:
      blog_dir: . # (1)!
  - search
  - tags
nav:
  - index.md

1. 这是重点——我们将博客托管在项目的根目录下，而不是子目录中。更多信息，请参阅blog_dir配置选项。

   ¥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 configuration option.

博客设置

¥Blog setup

博客索引页位于docs/index.md 。此页面由 MkDocs 预先填充了一些内容，因此我们将用引导博客所需的内容替换它：

¥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:

# Blog

就是这样。

¥That's it.

撰写你的第一篇文章

¥Writing your first post

现在我们已经设置好了内置的博客插件，可以开始撰写第一篇文章了。所有博客文章都使用与 Material for MkDocs 中已包含的 Markdown 风格编写。首先，创建一个名为posts的文件夹，其中包含一个名为hello-world.md的文件：

¥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:

.
├─ docs/
│  ├─ posts/
│  │  └─ hello-world.md # (1)!
│  └─ index.md
└─ mkdocs.yml

1. 如果您想以不同的方式排列帖子，您可以随意操作。URL 是根据post_url_format中指定的格式以及帖子的标题和日期构建的，无论它们在posts目录中如何组织。

   ¥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 and the titles and dates of posts, no matter how they are organized inside the posts directory.

然后，打开hello-world.md ，并添加以下行：

¥Then, open up hello-world.md, and add the following lines:

---
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:

然而，这仅仅是个开始。内置的博客插件包含日常博客所需的大量功能。访问插件文档，了解以下主题：

¥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:

• 添加摘录

  ¥Adding an excerpt

• 添加作者

  ¥Adding authors

• 添加类别

  ¥Adding categories

• 添加标签

  ¥Adding tags

• 添加相关链接

  ¥Adding related links

• 链接自和链接至帖子

  ¥Linking from and to posts

• 设定阅读时间

  ¥Setting the reading time

• 设置默认值

  ¥Setting defaults

此外，内置博客插件拥有数十个配置选项，方便您微调输出效果。您可以配置帖子标题、常规行为等等。

¥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.

下一步是什么？

¥What's next?

推出基本的博客支持是一项相当大的挑战——内置的博客插件可能是今年最大的更新，并且已经包含了很多功能。然而，Material for MkDocs 的应用场景多种多样，因此我们希望像往常一样进行迭代。

¥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.