内置博客插件¶
博客插件使得构建博客变得非常简单，无论是作为文档的附属部分还是作为主要内容。专注于您的内容，而插件负责所有繁重的工作，生成所有最新帖子、归档和分类页面、可配置的分页以及更多功能。
目标¶
工作原理¶
该插件扫描配置的posts目录中的.md文件，从中自动生成分页视图1。如果没有其他配置，插件期望您的项目具有以下目录结构，并会为您创建任何缺失的目录或文件：
blog目录中的index.md文件是您的博客的入口点——一个以逆时间顺序列出所有帖子的分页视图。除此之外，插件还支持自动创建归档和分类页面，这些页面列出特定时间段或类别的部分帖子。
帖子URL是完全可配置的，无论您是否希望URL包含帖子的日期。渲染的日期始终以您项目的站点语言的本地语言显示。与其他静态博客框架一样，帖子可以使用各种元数据进行注释，从而便于与其他内置插件集成，例如social和tags插件。
帖子可以使用适合您特定需求的嵌套文件夹进行组织，并可以利用Material for MkDocs提供的所有组件和语法，包括警告框、注释、代码块、内容标签、图表、图标、数学等。
何时使用¶
如果您想在项目中添加博客，或因其出色的技术写作能力而从其他博客框架迁移到Material for MkDocs，那么这个插件是一个不错的选择，因为它与许多其他内置插件完美集成：
配置¶
与所有内置插件一样，开始使用博客插件非常简单。只需将以下行添加到mkdocs.yml中，您就可以开始撰写您的第一篇帖子：
博客插件内置于Material for MkDocs中，无需安装。
导航¶
如果您在mkdocs.yml中没有配置站点导航，那么就没有其他操作。博客归档和分类页面将自动出现在自动生成的导航下方。
如果您定义了导航结构，则需要指定博客在其中的位置。为博客创建一个带有索引页面的导航部分：
归档和分类页面将作为该部分的子部分出现在博客部分的页面下。在这种情况下，它们将在index.md之后出现。index.md文件的路径必须与blog_dir匹配。这意味着您可以将博客导航条目的名称设置为您喜欢的任何名称：'博客'、'新闻'或'提示'。
一般设置¶
以下设置可用：
enabled¶
9.2.0 true
使用此设置在构建项目时启用或禁用插件。通常不需要指定此设置，但如果您想禁用插件，请使用：
blog_dir¶
9.2.0 blog
使用此设置更改博客在docs目录中的位置。该路径作为所有帖子和视图的前缀包含在生成的URL中。您可以通过以下方式更改它：
提供的路径是从docs目录解析的。
blog_toc¶
9.2.0 false
使用此设置利用目录在视图中显示帖子标题。如果您的帖子摘要相对较长，这可能会很有用。如果您想启用它，请使用：
帖子¶
以下设置可用于帖子：
post_dir¶
9.2.0 {blog}/posts
使用此设置更改帖子所在的文件夹。通常不需要更改此设置，但如果您想重命名文件夹或更改其文件系统位置，请使用：
请注意，posts目录仅用于帖子组织——它不包含在帖子URL中，因为它们是由此插件自动和方便地生成的。
以下占位符可用：
blog–blog目录
提供的路径是从docs目录解析的。
post_date_format¶
9.2.0 long
使用此设置更改帖子的日期格式。此插件使用babel在配置的站点语言中呈现日期。您可以使用babel的模式语法或以下短代码：
请注意，根据站点语言，结果在其他语言中可能看起来不同。
post_url_date_format¶
9.2.0 yyyy/MM/dd
使用此设置更改帖子URL中使用的日期格式。格式字符串必须遵循babel的模式语法，并且不应包含空格。一些流行的选择：
如果您想从帖子URL中删除日期，例如，当您的博客主要包含常青内容时，您可以从post_url_format格式字符串中删除date占位符。
post_url_format¶
9.2.0 {date}/{slug}
使用此设置更改生成帖子URL时使用的格式字符串。您可以自由组合占位符，并用斜杠或其他字符连接它们：
以下占位符可用：
categories– 帖子类别，使用categories_slugify进行slug化date– 帖子日期，使用post_url_date_format格式化slug– 帖子标题，使用post_slugify进行slug化，或通过slug元数据属性显式设置file– 不带.md文件扩展名的帖子文件名
如果您删除date占位符，请确保帖子URL不会与blog目录下托管的其他页面的URL冲突，因为这会导致未定义的行为。
post_url_max_categories¶
9.2.0 1
使用此设置设置包含在帖子URL中的类别数量的上限，如果categories占位符是post_url_format的一部分，并且帖子定义了类别：
如果给定多个类别，它们将在slug化后用/连接。
post_slugify¶
使用此设置更改生成URL兼容slug的函数。默认情况下，使用Python Markdown扩展中的slugify函数，如下所示：
默认配置是Unicode感知的，应该为所有语言生成良好的slug。当然，您也可以提供自定义slug化函数以获得更细粒度的控制。
post_slugify_separator¶
9.2.0 -
使用此设置更改传递给作为post_slugify一部分的slug化函数的分隔符。虽然默认值是连字符，但可以设置为任何字符串，例如_：
post_excerpt¶
9.2.0 optional
默认情况下，插件使帖子摘要成为可选的。当帖子未定义摘要时，视图包括整个帖子。此设置可用于使帖子摘要成为必需：
当帖子摘要是必需的时，没有摘要分隔符的帖子会引发错误。因此，当您想确保所有帖子都有定义的摘要时，此设置非常有用。
post_excerpt_max_authors¶
9.2.0 1
使用此设置设置在帖子摘要中呈现的作者数量的上限。虽然每个帖子可以由多个作者撰写，但此设置允许限制显示为几个或甚至一个作者，或在帖子摘要中禁用作者：
这仅适用于视图中的帖子摘要。帖子始终呈现所有作者。
post_excerpt_max_categories¶
9.2.0 5
使用此设置设置在帖子摘要中呈现的类别数量的上限。虽然每个帖子可以分配给多个类别，但此设置允许限制显示为几个或甚至一个类别，或在帖子摘要中禁用类别：
这仅适用于视图中的帖子摘要。帖子始终呈现所有类别。
post_excerpt_separator¶
9.2.0 <!-- more -->
使用此设置设置插件在生成帖子摘要时将在帖子内容中查找的分隔符。所有内容__在__分隔符之前被视为摘要的一部分：
使用HTML注释作为分隔符是常见做法。
post_readtime¶
9.2.0 true
使用此设置控制插件是否应自动计算帖子的阅读时间，然后在帖子摘要以及帖子本身中呈现：
中文、日文和韩文字符
当前阅读时间计算不考虑中文、日文和韩文字符的分段。这意味着这些语言的帖子阅读时间可能不准确。我们计划在未来添加支持。在此之前，请使用readtime前置属性设置阅读时间。
post_readtime_words_per_minute¶
9.2.0 265
使用此设置更改计算帖子阅读时间时预期的每分钟阅读单词数。如果您想微调它，请使用：
265个单词每分钟的阅读时间被认为是成年人的平均阅读时间。
归档¶
以下设置适用于归档页面：
archive¶
9.2.0 true
使用此设置启用或禁用归档页面。归档页面显示特定时间段（例如年份、月份等）的所有帖子，按逆序排列。如果您想禁用归档页面，请使用：
archive_name¶
使用此设置更改插件添加到导航中的归档部分的标题。如果省略此设置，则从翻译中获取。如果您想更改它，请使用：
archive_date_format¶
9.2.0 yyyy
使用此设置更改归档页面标题中使用的日期格式。格式字符串必须遵循babel的模式语法。一些流行的选择：
请注意，根据站点语言，结果在其他语言中可能看起来不同。
archive_url_date_format¶
9.2.0 yyyy
使用此设置更改归档页面URL中使用的日期格式。格式字符串必须遵循babel的模式语法，并且不应包含空格。一些流行的选择：
archive_url_format¶
9.2.0 archive/{date}
使用此设置更改生成归档页面URL时使用的格式字符串。您可以自由组合占位符，并用斜杠或其他字符连接它们：
以下占位符可用：
date– 归档日期，使用archive_url_date_format格式化
archive_pagination¶
9.7.0 true
使用此设置启用或禁用归档页面的分页。此设置的值继承自pagination，除非显式设置。要禁用分页，请使用：
archive_pagination_per_page¶
9.7.0 10
使用此设置更改每个归档页面呈现的帖子数量。此设置的值继承自pagination_per_page，除非显式设置。要更改它，请使用：
archive_toc¶
9.2.0 false
使用此设置利用目录在所有归档页面上显示帖子标题。此设置的值继承自blog_toc，除非显式设置。要更改它，请使用：
分类¶
以下设置适用于分类页面：
categories¶
9.2.0 true
使用此设置启用或禁用分类页面。分类页面按逆时间顺序显示特定类别的所有帖子。如果您想禁用分类页面，请使用：
categories_name¶
使用此设置更改插件添加到导航中的分类部分的标题。如果省略此设置，则从翻译中获取。如果您想更改它，请使用：
categories_url_format¶
9.2.0 category/{slug}
使用此设置更改生成分类页面URL时使用的格式字符串。您可以自由组合占位符，并用斜杠或其他字符连接它们：
以下占位符可用：
slug– 类别，使用categories_slugify进行slug化
categories_slugify¶
使用此设置更改生成URL兼容slug的函数。默认情况下，使用Python Markdown扩展中的slugify函数，如下所示：
默认配置是Unicode感知的，应该为所有语言生成良好的slug。当然，您也可以提供自定义slug化函数以获得更细粒度的控制。
categories_slugify_separator¶
9.2.0 -
使用此设置更改传递给作为categories_slugify一部分的slug化函数的分隔符。虽然默认值是连字符，但可以设置为任何字符串，例如_：
categories_sort_by¶
9.7.0 material.plugins.blog.view_name
使用此设置指定自定义函数以对类别进行排序。例如，如果您想按包含的帖子数量对类别进行排序，请使用以下配置：
不要忘记启用categories_sort_reverse。您可以定义自己的比较函数，该函数必须返回可以在排序时进行比较的内容，即字符串或数字。
categories_sort_reverse¶
9.7.0 false
使用此设置反转类别的排序顺序。默认情况下，类别按升序排序，但您可以按如下方式反转排序：
categories_allowed¶
插件允许根据预定义列表检查类别，以捕捉拼写错误或确保类别不会被任意添加。使用以下方式指定您要允许的类别：
如果帖子引用的类别不在此列表中，插件将在构建时停止。可以通过categories元数据属性将帖子分配给类别。
categories_pagination¶
9.7.0 true
使用此设置启用或禁用分类页面的分页。此设置的值继承自pagination，除非显式设置。要禁用分页，请使用：
categories_pagination_per_page¶
9.7.0 10
使用此设置更改每个分类页面呈现的帖子数量。此设置的值继承自pagination_per_page，除非显式设置。要更改它，请使用：
categories_toc¶
9.2.0 false
使用此设置利用目录在所有分类页面上显示帖子标题。此设置的值继承自blog_toc，除非显式设置。要更改它，请使用：
作者¶
以下设置适用于作者：
authors¶
9.2.0 true
使用此设置启用或禁用帖子作者。如果启用此设置，插件将查找名为.authors.yml的文件，并在帖子和视图中呈现作者。要禁用此行为，请使用：
authors_file¶
9.2.0 {blog}/.authors.yml
使用此设置更改存储帖子作者信息的文件路径。通常不需要更改此设置，但如果需要，请使用：
以下占位符可用：
blog–blog目录
提供的路径是从docs目录解析的。
作者信息格式
.authors.yml文件必须遵循以下格式：
authors:
<author>:
name: string # 作者姓名
description: string # 作者描述
avatar: url # 作者头像
slug: url # 作者个人资料slug
url: url # 作者网站URL
请注意，<author>必须设置为一个标识符，以将作者与帖子关联，例如，像squidfunk这样的GitHub用户名。然后可以在帖子的authors元数据属性中使用此标识符。支持多个作者。作为示例，请参见我们博客中使用的.authors.yml文件。
authors_profiles¶
9.7.0 false
使用此设置启用或禁用自动生成的作者个人资料。作者个人资料按逆时间顺序显示作者的所有帖子。您可以通过以下方式启用作者个人资料：
authors_profiles_name¶
使用此设置更改插件添加到导航中的作者部分的标题。如果省略此设置，则从翻译中获取。如果您想更改它，请使用：
authors_profiles_url_format¶
9.7.0 author/{slug}
使用此设置更改生成作者个人资料URL时使用的格式字符串。您可以自由组合占位符，并用斜杠或其他字符连接它们：
以下占位符可用：
slug– 作者slug或来自authors_file的标识符name– 来自authors_file的作者姓名
authors_profiles_pagination¶
9.7.0 true
使用此设置启用或禁用作者个人资料的分页。此设置的值继承自pagination，除非显式设置。要禁用分页，请使用：
authors_profiles_pagination_per_page¶
9.7.0 10
使用此设置更改每个归档页面呈现的帖子数量。此设置的值继承自pagination_per_page，除非显式设置。要更改它，请使用：
authors_profiles_toc¶
9.7.0 false
使用此设置利用目录在所有作者个人资料上显示帖子标题。此设置的值继承自blog_toc，除非显式设置。要更改它，请使用：
分页¶
以下设置适用于分页：
pagination¶
9.2.0 true
使用此设置启用或禁用视图中的分页——生成的页面显示帖子或部分帖子，按逆时间顺序排列。如果您想禁用分页，请使用：
pagination_per_page¶
9.2.0 10
使用此设置更改每页呈现的帖子数量。如果您的帖子摘要相对较长，减少每页的帖子数量可能是个好主意：
pagination_url_format¶
9.2.0 page/{page}
使用此设置更改生成分页视图URL时使用的格式字符串。您可以自由组合占位符，并用斜杠或其他字符连接它们：
以下占位符可用：
page– 页码
pagination_format¶
9.2.0 ~2~
插件使用paginate模块生成分页标记，使用特殊语法。使用此设置自定义分页的构造方式。一些流行的选择：
以下占位符由paginate支持：
$first_page– 第一个可达页面的编号$last_page– 最后一个可达页面的编号$page– 当前选定页面的编号$page_count– 可达页面的数量$items_per_page– 每页的最大项目数$first_item– 当前页面上第一个项目的索引$last_item– 当前页面上最后一个项目的索引$item_count– 项目的总数$link_first– 链接到第一页（除非在第一页）$link_last– 链接到最后一页（除非在最后一页）$link_previous– 链接到上一页（除非在第一页）$link_next– 链接到下一页（除非在最后一页）
pagination_if_single_page¶
9.2.0 false
使用此设置控制当视图仅包含单个页面时是否应自动禁用分页。如果您希望始终呈现分页，请使用：
pagination_keep_content¶
9.2.0 false
使用此设置启用或禁用内容的持久性，即分页视图是否也应显示其包含视图的内容。如果您想启用此行为，请使用：
草稿¶
以下设置适用于草稿：
draft¶
9.2.0 false
渲染草稿帖子在部署预览中可能很有用。使用此设置指定插件在构建项目时是否应包含标记为草稿的帖子：
draft_on_serve¶
9.2.0 true
使用此设置控制插件在预览您的站点时是否应包含标记为草稿的帖子。如果您不希望在预览时包含草稿帖子，请使用：
draft_if_future_date¶
9.2.0 false
插件可以自动将未来日期的帖子标记为草稿。当日期超过今天时，帖子会在构建项目时自动包含，除非明确标记为草稿：
用法¶
元数据¶
帖子可以定义一组元数据属性，指定插件如何呈现它们、它们在何种视图中集成以及它们如何相互链接。每个帖子的元数据会根据模式进行验证，以便更快地发现语法错误。
以下属性可用：
authors¶
使用此属性通过提供在authors_file中定义的标识符列表将帖子与[作者]关联。如果无法解析作者，插件将终止并显示错误：
- 作者通过其标识符链接。作为示例，请参见我们博客中使用的
.authors.yml文件。
categories¶
使用此属性将帖子与一个或多个[类别][category]关联，使帖子成为生成的类别页面的一部分。类别定义为字符串列表（允许空格）：
如果您想防止意外拼写错误将类别分配给帖子，可以使用categories_allowed设置在mkdocs.yml中设置预定义的允许类别列表。
date¶
使用此属性指定帖子的日期。请注意，此属性是必需的，这意味着如果未设置，则构建失败。可以使用稍微不同的语法设置其他日期：
支持以下日期格式：
2024-01-312024-01-31T12:00:00
draft¶
使用此属性将帖子标记为草稿。插件允许在构建项目时使用draft设置包含或排除标记为草稿的帖子。将帖子标记为草稿：
pin¶
9.7.0 false
使用此属性将帖子固定在视图的顶部。如果多个帖子被固定，则固定的帖子按降序排序，并出现在所有其他帖子之前。将帖子固定：
links¶
使用此属性定义在帖子侧边栏中呈现的链接列表。该属性遵循与mkdocs.yml中的nav相同的语法，支持部分甚至锚点：
---
links:
- plugins/search.md # (1)!
- Insiders:
- insiders/how-to-sponsor.md
- insiders/getting-started.md#requirements
---
# 帖子标题
...
- 如果链接定义了锚点，插件将从链接页面解析锚点，并将锚点标题设置为副标题。
所有相对链接都是从docs目录解析的。
readtime¶
使用此属性显式设置帖子的阅读时间（以分钟为单位）。当启用post_readtime时，插件计算帖子的阅读时间，可以用以下方式覆盖：
slug¶
使用此属性显式设置帖子的slug。默认情况下，帖子的slug是由post_slugify函数从帖子的标题自动计算的，可以用以下方式覆盖：
Slugs被传递给post_url_format。