设置博客¶

¥Setting up a blog¶

Material for MkDocs 让您轻松创建博客，既可以作为文档的附属组件，也可以独立运行。您只需专注于内容，引擎将自动处理所有繁重工作，自动生成存档和类别索引、帖子 slug 、可配置分页等。

¥Material for MkDocs makes it very easy to build a blog, either as a sidecar to your documentation or standalone. Focus on your content while the engine does all the heavy lifting, automatically generating archive and category indexes, post slugs, configurable pagination and more.

查看我们的博客，它是使用新的内置博客插件创建的！

¥Check out our blog, which is created with the new built-in blog plugin!

配置¶

¥Configuration¶

内置博客插件¶

¥Built-in blog plugin¶

9.2.0创建博客

¥9.2.0 create-blog

内置博客插件新增了从帖子文件夹构建博客的功能，这些帖子带有日期和其他结构化数据的注释。首先，将以下几行添加到mkdocs.yml中：

¥The built-in blog plugin adds support for building a blog from a folder of posts, which are annotated with dates and other structured data. First, add the following lines to mkdocs.yml:

plugins:
  - blog

如果您的mkdocs.yml中没有定义导航 ( nav )，则无需执行任何其他操作，因为博客插件会自动添加导航。如果您定义了导航，则只需将博客索引页添加到其中即可。您不需要也不应该添加单独的博客文章。例如：

¥If you do not have a navigation (nav) definition in your mkdocs.yml then there is nothing else to do there as the blog plugin will add navigation automatically. If you do have a navigation defined then you need to add the blog index page only to it. You need not and should not add the individual blog posts. For example:

nav:
  - index.md
  - Blog:
    - blog/index.md

有关所有设置的列表，请参阅插件文档。

¥For a list of all settings, please consult the plugin documentation.

高级设置¶

¥Advanced settings¶

insiders-4.44.0

¥ insiders-4.44.0

以下高级设置目前仅供我们的赞助商使用。这些设置完全是可选的，不会影响博客的功能，但有助于进行自定义：

¥The following advanced settings are currently reserved to our sponsors. They are entirely optional, and don't affect the functionality of the blog, but can be helpful for customizations:

当我们发现新的用例时，我们会在这里添加更多设置。

¥We'll add more settings here, as we discover new use cases.

RSS¶

¥RSS¶

9.2.0 RSS

¥9.2.0 rss

内置博客插件与RSS 插件无缝集成，提供了一种将 RSS 源添加到博客（或整个文档）的简单方法。使用pip安装：

¥The built-in blog plugin integrates seamlessly with the RSS plugin, which provides a simple way to add an RSS feed to your blog (or to your whole documentation). Install it with pip:

pip install mkdocs-rss-plugin

然后，将以下行添加到mkdocs.yml ：

¥Then, add the following lines to mkdocs.yml:

plugins:
  - rss:
      match_path: blog/posts/.* # (1)!
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags # (2)!

RSS 插件允许过滤要包含在 feed 中的 URL。在本例中，只有博客文章才会包含在 feed 中。
如果您想在 feed 中包含帖子的类别及其标签，请在此处添加categories和tags 。

支持以下配置选项：

¥The RSS plugin allows to filter for URLs to be included in the feed. In this example, only blog posts will be part of the feed.

enabled

true此选项指定在构建项目时是否启用该插件。如果您想加快本地构建速度，可以使用环境变量：

¥If you want to include a post's categories as well as its tags in the feed, add both categories and tags here.

plugins:
  - rss:
      enabled: !ENV [CI, false]

match_path

.*此选项指定哪些页面应包含在 Feed 中。例如，若要仅包含博客文章，请使用以下正则表达式：

¥The following configuration options are supported:

plugins:
  - rss:
      match_path: blog/posts/.*

date_from_meta

此选项指定应使用哪个前置属性作为 Feed 中页面的创建日期。建议使用date属性：

¥true This option specifies whether the plugin is enabled when building your project. If you want to speed up local builds, you can use an environment variable:

plugins:
  - rss:
      date_from_meta:
        as_creation: date

categories

此选项指定哪些前置内容属性将用作 feed 的类别。如果您使用categories和tags ，请同时添加以下几行：

¥.* This option specifies which pages should be included in the feed. For example, to only include blog posts in the feed, use the following regular expression:

plugins:
  - rss:
      categories:
        - categories
        - tags

comments_path

此选项指定帖子或页面评论的锚点。如果您集成了评论系统，请添加以下几行：

¥ This option specifies which front matter property should be used as a creation date of a page in the feed. It's recommended to use the date property:

plugins:
  - rss:
      comments_path: "#__comments"

MkDocs 的材料将自动向您的网站添加必要的元数据，从而使浏览器和阅读器能够发现 RSS 提要。

¥ This option specifies which front matter properties are used as categories as part of the feed. If you use categories and tags, add both with the following lines:

此扩展的其他配置选项未得到 Material for MkDocs 的官方支持，因此可能会产生意外结果。使用它们的风险由您自行承担。

¥ This option specifies the anchor at which comments for a post or page can be found. If you've integrated a comment system, add the following lines:

仅限博客¶

¥Blog only¶

你可能需要创建一个不包含任何文档的纯博客。在这种情况下，你可以创建如下目录树：

¥Material for MkDocs will automatically add the necessary metadata to your site which will make the RSS feed discoverable by browsers and feed readers.

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

请注意， posts目录位于docs的根目录中，没有中间的blog目录。
¥Notice that the posts directory is in the root of docs without intermediate blog directory.

并将以下行添加到mkdocs.yml ：

¥The other configuration options of this extension are not officially supported by Material for MkDocs, which is why they may yield unexpected results. Use them at your own risk.

plugins:
  - blog:
      blog_dir: . # (1)!

有关blog_dir设置的更多信息，请参阅插件文档。
¥Please see the plugin documentation for more information about the blog_dir setting.

通过此配置，博客文章的 url 将为/<post_slug>而不是/blog/<post_slug> 。

¥You might need to build a pure blog without any documentation. In this case, you can create a folder tree like this:

用法¶

¥Usage¶

撰写你的第一篇文章¶

¥Writing your first post¶

成功设置内置博客插件后，就可以开始撰写您的第一篇文章了。该插件不要求任何特定的目录结构，因此您可以完全自由地组织文章，只要它们都位于posts目录中即可：

¥And add the following lines to mkdocs.yml:

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

如果您想以不同的方式排列帖子，您可以随意操作。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的新文件并添加以下行：

¥With this configuration, the url of the blog post will be /<post_slug> instead of /blog/<post_slug>.

---
draft: true # (1)!
date: 2024-01-31 # (2)!
categories:
  - Hello
  - World
---

# Hello world!
...

如果您将帖子标记为草稿，则在索引页上的帖子日期旁边会出现一个红色标记。网站构建完成后，草稿不会包含在输出中。此行为可以更改，例如，在构建部署预览时渲染草稿。
如果您希望提供多个日期，则可以使用以下语法，允许您定义上次更新博客文章的日期+可以添加到模板的其他自定义日期：
```
---
date:
  created: 2022-01-31
  updated: 2022-02-02
---

# Hello world!
```
```
---
date:
  created: 2022-01-31
  updated: 2022-02-02
---

# Hello world!
```
--- date: created: 2022-01-31 updated: 2022-02-02 --- # Hello world! ---日期：创建：2022-01-31更新：2022-02-02 --- # 你好，世界！请注意，必须在date.created下设置创建日期，因为每篇博文都必须设置创建日期。

当你启动实时预览服务器时，你应该会看到你的第一篇帖子！你还会发现，存档和分类索引已经自动生成了。

¥After you've successfully set up the built-in blog plugin, it's time to write your first post. The plugin doesn't assume any specific directory structure, so you're completely free in how you organize your posts, as long as they are all located inside the posts directory:

添加摘录¶

¥Adding an excerpt¶

博客索引、存档和分类索引可以列出每篇文章的全文，也可以列出文章的摘录。可以在文章的前几段后添加分隔符来创建摘录：

¥Create a new file called hello-world.md and add the following lines:

# Hello world!

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.

<!-- more -->
...

当内置博客插件生成所有索引时，摘录分隔符之前的内容会被自动提取，从而允许用户在决定阅读之前开始阅读帖子。

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

添加作者¶

¥Adding authors¶

为了给你的文章增添一些个性，你可以将每篇文章与一个或多个作者关联。首先，在你的博客目录中创建.authors.yml文件，并添加一个作者：

¥If you wish to provide multiple dates, you can use the following syntax, allowing you to define a date when you last updated the blog post + further custom dates you can add to the template:

authors:
  squidfunk:
    name: Martin Donath
    description: Creator
    avatar: https://github.com/squidfunk.png

.authors.yml文件将每个作者与一个标识符（本例中squidfunk ）关联，以便在文章中使用。可以配置不同的属性。有关所有可用属性的列表，请参阅author_file文档。

¥Note that the creation date must be set under date.created, as each blog post must have a creation date set.

现在，您可以通过在 Markdown 文件头文件中的authors属性下引用作者标识符，为文章分配一个或多个作者。每位作者的简介都会显示在每篇文章的左侧边栏以及索引页的文章摘录中：

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

---
date: 2024-01-31
authors:
  - squidfunk
    ...
---

# Hello world!
...

添加作者简介¶

¥Adding author profiles¶

insiders-4.46.0

¥The blog index, as well as archive and category indexes can either list the entire content of each post, or excerpts of posts. An excerpt can be created by adding a  separator after the first few paragraphs of a post:

如果您希望为每位作者添加专用页面，可以通过将author_profiles配置选项设置为true来启用作者个人资料。只需将以下几行添加到mkdocs.yml即可：

¥When the built-in blog plugin generates all indexes, the content before the excerpt separator is automatically extracted, allowing the user to start reading a post before deciding to jump in.

plugins:
  - blog:
      authors_profiles: true

如果将其与自定义索引页结合使用，您可以为每位作者创建一个专用页面，其中包含简短描述、社交媒体链接等——基本上任何可以用 Markdown 编写的内容都可以。文章列表将附加在页面内容之后。

¥In order to add a little more personality to your posts, you can associate each post with one or multiple authors. First, create the .authors.yml file in your blog directory, and add an author:

添加类别¶

¥Adding categories¶

分类是将文章按主题分组到专用索引页的绝佳方式。这样，对特定主题感兴趣的用户可以浏览您关于该主题的所有文章。请确保已启用分类，并将其添加到首页的categories属性中：

¥The .authors.yml file associates each author with an identifier (in this example squidfunk), which can then be used in posts. Different attributes can be configured. For a list of all possible attributes, please consult the authors_file documentation.

---
date: 2024-01-31
categories:
  - Hello
  - World
---

# Hello world!
...

如果您想避免在输入类别时出现拼写错误，可以在mkdocs.yml categories_allowed配置选项中定义所需的类别。如果在列表中找不到类别，内置博客插件将停止构建。

¥Now, you can assign one or more authors to a post by referencing their identifiers in the front matter of the Markdown file under the authors property. For each author, a small profile is rendered in the left sidebar of each post, as well as in post excerpts on index pages:

添加标签¶

¥Adding tags¶

除了类别之外，内置博客插件还集成了内置标签插件。如果您在文章的 front matter tags属性中添加标签作为文章的一部分，则该文章将从标签索引中链接：

¥ insiders-4.46.0

---
date: 2024-01-31
tags:
  - Foo
  - Bar
---

# Hello world!
...

与往常一样，标签会显示在主标题上方，如果已配置，帖子会链接到标签索引页。请注意，帖子作为页面，仅与其标题链接。

¥If you wish to add a dedicated page for each author, you can enable author profiles by setting the authors_profiles configuration option to true. Just add the following lines to mkdocs.yml:

更换弹头¶

¥Changing the slug¶

Slug 是 URL 中使用的文章的简短描述。它们是自动生成的，但您可以为页面指定自定义 slug：

¥If you combine this with custom index pages, you can create a dedicated page for each author with a short description, social media links, etc. – basically anything you can write in Markdown. The list of posts is then appended after the content of the page.

---
slug: hello-world
---

# Hello there world!
...

¥Adding related links¶

9.6.0

¥Categories are an excellent way for grouping your posts thematically on dedicated index pages. This way, a user interested in a specific topic can explore all of your posts on this topic. Make sure categories are enabled and add them to the front matter categories property:

相关链接是在您的文章左侧边栏中突出显示延伸阅读部分的绝佳方式，可引导用户访问文档的其他部分。使用前置links属性，即可为文章添加相关链接：

¥If you want to save yourself from typos when typing out categories, you can define your desired categories in mkdocs.yml as part of the categories_allowed configuration option. The built-in blog plugin will stop the build if a category is not found within the list.

---
date: 2024-01-31
links:
  - plugins/search.md
  - insiders/how-to-sponsor.md
---

# Hello world!
...

您可以使用与mkdocs.yml中的nav部分完全相同的语法，这意味着您可以为链接设置明确的标题，添加外部链接，甚至使用嵌套：

¥Besides categories, the built-in blog plugin also integrates with the built-in tags plugin. If you add tags in the front matter tags property as part of a post, the post is linked from the tags index:

---
date: 2024-01-31
links:
  - plugins/search.md
  - insiders/how-to-sponsor.md
  - Nested section:
    - External link: https://example.com
    - setup/setting-up-site-search.md
---

# Hello world!
...

如果仔细观察，你会发现甚至可以使用锚点链接到文档的特定部分，从而扩展mkdocs.yml中nav语法的可能性。内置的博客插件会解析锚点，并将锚点的标题设置为相关链接的副标题。

¥As usual, the tags are rendered above the main headline and posts are linked on the tags index page, if configured. Note that posts are, as pages, only linked with their titles.

请注意，所有链接都必须相对于docs_dir ， nav设置也是如此。

¥Slugs are the shortened description of your post used in the URL. They are automatically generated, but you can specify a custom slug for a page:

链接自和链接至帖子¶

¥Linking from and to posts¶

虽然帖子 URL是动态计算的，但内置博客插件会确保所有来自和指向帖子以及帖子资源的链接都是正确的。如果您想链接到某个帖子，只需使用 Markdown 文件的路径作为链接引用（链接必须是相对的）：

¥9.6.0

[Hello World!](blog/posts/hello-world.md)

从帖子链接到页面（例如索引）遵循相同的方法：

¥Related links offer the perfect way to prominently add a further reading section to your post that is included in the left sidebar, guiding the user to other destinations of your documentation. Use the front matter links property to add related links to a post:

[Blog](../index.md)

在网站构建时， posts目录中的所有资源都会复制到blog/assets文件夹中。当然，您也可以引用posts目录之外的文章资源。内置的博客插件会确保所有链接正确无误。

¥You can use the exact same syntax as for the nav section in mkdocs.yml, which means you can set explicit titles for links, add external links and even use nesting:

置顶帖子¶

¥Pinning a post¶

insiders-4.53.0

¥If you look closely, you'll realize that you can even use an anchor to link to a specific section of a document, extending the possibilities of the nav syntax in mkdocs.yml. The built-in blog plugin resolves the anchor and sets the title of the anchor as a subtitle of the related link.

如果您想要将帖子固定到索引页的顶部以及它所属的存档和类别索引的顶部，则可以使用前置pin属性：

¥Note that all links must be relative to docs_dir, as is also the case for the nav setting.

---
date: 2024-01-31
pin: true
---

# Hello world!
...

如果置顶了多个帖子，则按创建日期排序，最新置顶的帖子将首先显示，然后按降序显示其他置顶帖子。

¥While post URLs are dynamically computed, the built-in blog plugin ensures that all links from and to posts and a post's assets are correct. If you want to link to a post, just use the path to the Markdown file as a link reference (links must be relative):

设定阅读时间¶

¥Setting the reading time¶

启用后，系统会计算每篇文章的预期阅读时间，并将其呈现为文章和文章摘录的一部分。如今，许多博客都会显示阅读时间，因此内置博客插件也提供了此功能。

¥Linking from a post to a page, e.g. the index, follows the same method:

然而，有时计算出来的阅读时间可能感觉不准确，或者得出一些奇怪的数字。因此，可以使用文章前置的readtime属性来覆盖并明确设置阅读时间：

¥All assets inside the posts directory are copied to the blog/assets folder when the site is being built. Of course, you can also reference assets from posts outside of the posts directory. The built-in blog plugin ensures that all links are correct.

---
date: 2024-01-31
readtime: 15
---

# Hello world!
...

这将禁用自动阅读时间计算。

¥ insiders-4.53.0

中文、日文和韩文字符

¥If you want to pin a post to the top of the index page, as well as the archive and category indexes it is part of, you can use the front matter pin property:

目前，阅读时间计算尚未考虑中文、日文和韩文字符的分割。这意味着这些语言的帖子的阅读时间可能不准确。我们计划在未来添加此功能。在此期间，请使用前置内容中的readtime属性来设置阅读时间。

¥If multiple posts are pinned, they are sorted by their creation date, with the most recent pinned post being shown first, followed by the other pinned posts in descending order.

设置默认值¶

¥Setting defaults¶

9.6.0元 – 内置

¥When enabled, the reading the expected reading time of each post is computed, which is rendered as part of the post and post excerpt. Nowadays, many blogs show reading times, which is why the built-in blog plugin offers this capability as well.

如果您有很多帖子，为每篇帖子定义上述所有属性可能会显得多余。幸运的是，内置的元插件允许您为每个文件夹设置默认的前置属性。您可以按类别或作者对帖子进行分组，并添加.meta.yml文件来设置常用属性：

¥Sometimes, however, the computed reading time might not feel accurate, or result in odd and unpleasant numbers. For this reason, reading time can be overridden and explicitly set with the front matter readtime property for a post:

.
├─ docs/
│  └─ blog/
│     ├─ posts/
│     ├─ .meta.yml # (1)!
│     └─ index.md
└─ mkdocs.yml

如前所述，您还可以在posts目录的嵌套文件夹中放置一个.meta.yml文件。该文件可以定义所有在文章中有效的前置属性，例如：
```
authors:
  - squidfunk
categories:
  - Hello
  - World
```
```
authors:
  - squidfunk
categories:
  - Hello
  - World
```
authors: - squidfunk categories: - Hello - World作者： - squidfunk类别： - 你好- 世界

请注意顺序很重要——内置元插件必须在mkdocs.yml中的博客插件之前定义，以便内置博客插件正确获取所有设置的默认值：

¥This will disable automatic reading time computation.

plugins:
  - meta
  - blog

.meta.yml文件中的列表和字典与帖子定义的值合并并删除重复项，这意味着您可以在.meta.yml中定义通用属性，然后为每个帖子添加特定属性或覆盖。

¥Chinese, Japanese and Korean characters

添加页面¶

¥Adding pages¶

除了帖子之外，您还可以通过在mkdocs.yml的nav部分列出页面来将静态页面添加到您的博客。所有生成的索引都包含在最后一个指定页面之后。例如，要添加博客作者页面，请将以下内容添加到mkdocs.yml ：

¥Reading time computation currently does not take segmentation of Chinese, Japanese and Korean characters into account. This means that the reading time for posts in these languages may be inaccurate. We're planning on adding support in the future. In the meantime, please use the readtime front matter property to set the reading time.

nav:
  - Blog:
    - blog/index.md
    - blog/authors.md
      ...

定制¶

¥Customization¶

自定义索引页¶

¥Custom index pages¶

9.6.0

¥9.6.0 meta – built-in

如果您想要将自定义内容添加到自动生成的存档和类别索引中，例如在帖子列表之前添加类别描述，您可以在内置博客插件创建类别页面的同一位置手动创建类别页面：

¥If you have a lot of posts, it might feel redundant to define all of the above for each post. Luckily, the built-in meta plugin allows to set default front matter properties per folder. You can group your posts by categories, or authors, and add a .meta.yml file to set common properties:

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

最简单的方法是先将类别添加到博客文章中，然后获取内置博客插件生成的 URL，并在blog_dir文件夹中的相应位置创建文件。请注意，显示的目录列表基于默认配置。如果您为以下选项指定了不同的值，请务必相应地调整路径： blog_dir categories_url_format categories_slugify

您现在可以向新创建的文件添加任意内容，或为此页面设置特定的前端属性，例如更改页面描述：

¥As already noted, you can also place a .meta.yml file in nested folders of the posts directory. This file then can define all front matter properties that are valid in posts, e.g.:

---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
---

# Hello
...

所有属于该类别的帖子摘录都会自动附加。

¥Note that order matters – the built-in meta plugin must be defined before the blog plugin in mkdocs.yml, so that all set defaults are correctly picked up by the built-in blog plugin:

覆盖模板¶

¥Overriding templates¶

内置博客插件与 MkDocs 的 Material 建立在相同基础上，这意味着您可以像往常一样使用主题扩展覆盖博客使用的所有模板。

¥Lists and dictionaries in .meta.yml files are merged and deduplicated with the values defined for a post, which means you can define common properties in .meta.yml and then add specific properties or overrides for each post.

以下模板由内置博客插件添加：

¥Besides posts, it's also possible to add static pages to your blog by listing the pages in the nav section of mkdocs.yml. All generated indexes are included after the last specified page. For example, to add a page on the authors of the blog, add the following to mkdocs.yml:

blog.html – 博客、档案和类别索引的模板
¥blog_dir
blog-post.html – 博客文章模板
¥categories_url_format