Skip to content

内置博客插件

¥Built-in blog plugin

这款博客插件让您轻松创建博客，既可以作为文档的辅助，也可以作为主内容。您只需专注于内容本身，插件将为您完成所有繁重的工作，生成所有最新文章的视图、存档和分类页面、可配置的分页等等。

¥The blog plugin makes it very easy to build a blog, either as a sidecar to your documentation or as the main thing. Focus on your content while the plugin does all the heavy lifting, generating a view of all latest posts, archive and category pages, configurable pagination and much more.

客观的

¥Objective

工作原理

¥How it works

该插件会扫描已配置的帖子目录，查找.md文件，并自动生成分页视图1。如果没有其他配置，该插件会假设您的项目具有以下目录布局，并会为您创建任何缺失的目录或文件：

¥The plugin scans the configured posts directory for .md files from which paginated views1 are automatically generated. If not configured otherwise, the plugin expects that your project has the following directory layout, and will create any missing directories or files for you:

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

博客目录中的index.md文件是您博客的入口——一个分页视图，按时间倒序列出所有文章。此外，该插件还支持自动创建存档和分类页面，列出按时间段或类别划分的文章子集。

¥The index.md file in the blog directory is the entry point to your blog – a paginated view listing all posts in reverse chronological order. Besides that, the plugin supports automatically creating archive and category pages that list a subset of posts for a time interval or category.

帖子 URL完全可配置，无论您是否希望 URL 包含帖子日期。渲染的日期始终以项目站点语言的语言环境显示。与其他静态博客框架一样，帖子可以使用各种元数据进行注释，从而轻松与其他内置插件（例如社交和标签插件）集成。

¥Post URLs are completely configurable, no matter if you want your URLs to include the post's date or not. Rendered dates always display in the locale of the site language of your project. Like in other static blog frameworks, posts can be annotated with a variety of metadata, allowing for easy integration with other built-in plugins, e.g., the social and tags plugin.

帖子可以组织在嵌套文件夹中，目录布局可满足您的特定需求，并且可以利用 Material for MkDocs 提供的所有组件和语法，包括警告、注释、代码块、内容选项卡、图表、图标、数学等。

¥Posts can be organized in nested folders with a directory layout that suits your specific needs, and can make use of all components and syntax that Material for MkDocs offers, including admonitions, annotations, code blocks, content tabs, diagrams, icons, math, and more.

何时使用

¥When to use it

如果您想在项目中添加博客，或者由于其出色的技术写作功能而从其他博客框架迁移到 Material for MkDocs，那么此插件是一个很好的选择，因为它可以与许多其他内置插件完美集成：

¥If you want to add a blog to your project, or migrate from another blog framework to Material for MkDocs because of its excellent technical writing capabilities, this plugin is a great choice, as it integrates perfectly with many other built-in plugins:

  • 内置元插件元插件可以轻松地将元数据应用于帖子子集，包括作者、标签、类别、草稿状态以及社交卡片布局。更轻松地组织、分类和管理帖子元数据

  • 内置社交插件社交插件会自动为每篇文章和页面生成精美且可自定义的社交卡片，并在社交媒体上显示为预览。在社交媒体上分享时，指向您博客的链接会呈现精美的社交卡片。

  • 内置优化插件优化插件会使用压缩和转换技术自动识别并优化您在项目中引用的所有媒体文件。由于向用户提供更小的图片，您的博客加载速度更快。

  • 内置标签插件标签插件允许将文章与项目中的页面一起分类，以提高其可发现性，并将文章与文档关联起来。文档的标签系统已与您的博客集成

配置

¥Configuration

9.2.0博客 – 内置

¥   Built-in meta plugin

与所有内置插件一样，博客插件的入门非常简单。只需将以下几行添加到mkdocs.yml ，即可开始撰写您的第一篇文章：

¥The meta plugin makes it easy to apply metadata to a subset of posts, including authors, tags, categories, draft status, as well as social card layouts.

plugins:
  - blog

博客插件内置于 Material for MkDocs 中，无需安装。

¥Simpler organization, categorization and management of post metadata

¥Navigation

如果您没有在mkdocs.yml中配置站点导航，则无需执行任何其他操作。博客存档和分类页面将自动显示在自动生成的导航下方。

¥   Built-in social plugin

如果您已经定义了导航结构，则需要指定博客的显示位置。创建一个带有博客索引页的导航部分：

¥The social plugin automatically generates beautiful and customizable social cards for each post and page, showing as previews on social media.

theme:
  name: material
  features:
    - navigation.indexes
nav:
  - ...
  - Blog:
    - blog/index.md

存档和分类页面将作为博客版块页面下方的子版块出现在该版块中。在本例中，它们将出现在index.md之后index.md文件的路径必须与blog_dir匹配。这意味着您可以将博客导航条目命名为任何您喜欢的名称：“博客”、“新闻”或“技巧”。

¥Links to your blog render beautiful social cards when shared on social media

一般的

¥General

可用的设置如下：

¥   Built-in optimize plugin

enabled

¥enabled

9.2.0真

¥The optimize plugin automatically identifies and optimizes all media files that you reference in your project by using compression and conversion techniques.

使用此设置在构建项目时启用或禁用插件。通常不需要指定此设置，但如果您想禁用插件，请使用：

¥Your blog loads faster as smaller images are served to your users

plugins:
  - blog:
      enabled: false

blog_dir

¥blog_dir

9.2.0博客

¥   Built-in tags plugin

使用此设置可更改您的博客在docs 目录中的路径。该路径将作为所有文章和视图的前缀包含在生成的 URL 中。您可以使用以下命令更改它：

¥The tags plugin allows to categorize posts alongside with pages in your project, to improve their discoverability and connect posts to your documentation.

plugins:
  - blog:
      blog_dir: blog

plugins:
  - blog:
      blog_dir: .

提供的路径是从文档目录解析的。

¥Your documentation's tag system integrates with your blog

blog_toc

¥blog_toc

9.2.0错误

¥9.2.0 blog – built-in

使用此设置可以利用目录在视图中显示文章标题。如果您的文章摘录较长，此功能可能很有用。如果您想启用此功能，请使用：

¥As with all built-in plugins, getting started with the blog plugin is straightforward. Just add the following lines to mkdocs.yml, and you can start writing your first post:

plugins:
  - blog:
      blog_toc: true

帖子

¥Posts

帖子可以进行以下设置：

¥The blog plugin is built into Material for MkDocs and doesn't need to be installed.

post_dir

¥post_dir

9.2.0 {博客}/帖子

¥If you do not have site navigation configured in your mkdocs.yml then there is nothing more to do. The blog archive and category pages will automatically appear underneath the automatically generated navigation.

使用此设置可更改您的帖子所在的文件夹。通常无需更改此设置，但如果您想重命名文件夹或更改其文件系统位置，请使用：

¥If you do have a navigation structure defined then you will need to specify where the blog should appear in this. Create a navigation section with an index page for the blog:

plugins:
  - blog:
      post_dir: "{blog}/articles"

请注意，帖子目录仅用于帖子组织 - 它不包含在帖子 URL 中，因为它们是由该插件自动且舒适地生成的。

¥The archive and category pages will appear within that section as subsections beneath pages in the blog section. In this case, they would appear after index.md. The path to the index.md file must match blog_dir. This means that you can name the blog navigation entry anything you like: 'Blog' or 'News' or perhaps 'Tips'.

可用的占位符如下：

¥The following settings are available:

提供的路径是从文档目录解析的。

¥9.2.0 true

post_date_format

¥post_date_format

9.2.0长

¥Use this setting to enable or disable the plugin when building your project. It's normally not necessary to specify this setting, but if you want to disable the plugin, use:

使用此设置可更改帖子的日期格式。此插件使用Babel以配置的网站语言渲染日期。您可以使用Babel的模式语法或以下简码：

¥9.2.0 blog

plugins:
  - blog:
      post_date_format: full

plugins:
  - blog:
      post_date_format: long

plugins:
  - blog:
      post_date_format: medium

plugins:
  - blog:
      post_date_format: short

请注意，根据网站语言的不同，其他语言的结果可能会有所不同。

¥Use this setting to change the path where your blog is located in the docs directory. The path is included in the generated URLs as a prefix for all posts and views. You can change it with:

post_url_date_format

¥post_url_date_format

9.2.0年/月/日

¥The provided path is resolved from the docs directory.

使用此设置可更改帖子 URL 中使用的日期格式。格式字符串必须遵循babel的模式语法，且不得包含空格。一些常用的格式：

¥9.2.0 false

plugins:
  - blog:
      post_url_date_format: yyyy/MM/dd

plugins:
  - blog:
      post_url_date_format: yyyy/MM

plugins:
  - blog:
      post_url_date_format: yyyy

如果您想从帖子 URL 中删除日期，例如，当您的博客主要包含常青内容时，您可以从post_url_format格式字符串中删除date占位符。

¥Use this setting to leverage the table of contents to display post titles in views. This might be useful, if your post excerpts are rather long. If you want to enable it, use:

post_url_format

¥post_url_format

9.2.0 {日期}/{slug}

¥The following settings are available for posts:

使用此设置可更改生成帖子 URL 时使用的格式字符串。您可以自由组合占位符，并使用斜杠或其他字符连接它们：

¥9.2.0 {blog}/posts

plugins:
  - blog:
      post_url_format: "{date}/{slug}"

plugins:
  - blog:
      post_url_format: "{slug}"

可用的占位符如下：

¥Use this setting to change the folder where your posts are located. It's normally not necessary to change this setting, but if you want to rename the folder or change its file system location, use:

  • categories – 文章分类，使用categories_slugify进行 slugify

    ¥categories – Post categories, slugified with categories_slugify

  • date – 发布日期，使用post_url_date_format格式化

    ¥date – Post date, formatted with post_url_date_format

  • slug – 文章标题，使用post_slugify进行 slugify，或通过slug元数据属性明确设置

    ¥slug – Post title, slugified with post_slugify, or explicitly set via slug metadata property

  • file – 发布不带.md文件扩展名的文件名

    ¥file – Post filename without .md file extension

如果删除date占位符，请确保帖子 URL 不会与博客目录下托管的其他页面的 URL 冲突，因为这会导致未定义的行为。

¥Note that the posts directory is solely used for post organization – it is not included in post URLs, since they are automatically and comfortably generated by this plugin.

post_url_max_categories

¥post_url_max_categories

9.2.01

¥The following placeholders are available:

如果categories占位符是post_url_format的一部分并且帖子定义了类别，则使用此设置来设置帖子 URL 中包含的类别数量的上限：

¥The provided path is resolved from the docs directory.

plugins:
  - blog:
      post_url_format: "{categories}/{slug}"
      post_url_max_categories: 2

如果给出了多个类别，则在 slugifying 之后用/将它们连接起来。

¥9.2.0 long

post_slugify

¥post_slugify

9.2.0 pymdownx.slugs.slugify

¥Use this setting to change the date format of posts. This plugin uses babel to render dates in the configured site language. You can use babel's pattern syntax or the following shortcodes:

使用此设置可更改从文章标题生成 URL 兼容 slug 的函数。默认情况下，使用Python Markdown 扩展中的slugify函数，如下所示：

¥Note that depending on the site language, results might look different for other languages.

plugins:
  - blog:
      post_slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

默认配置支持 Unicode，应该能为所有语言生成良好的 slug。当然，您也可以提供自定义 slugification 函数，以实现更精细的控制。

¥9.2.0 yyyy/MM/dd

post_slugify_separator

¥post_slugify_separator

9.2.0-

¥Use this setting to change the date format used in post URLs. The format string must adhere to babel's pattern syntax and should not contain whitespace. Some popular choices:

使用此设置可以更改传递给post_slugify函数的分隔符。默认值为连字符，但可以设置为任何字符串，例如_ ：

¥If you want to remove the date from post URLs, e.g., when your blog features mostly evergreen content, you can remove the date placeholder from the post_url_format format string.

plugins:
  - blog:
      post_slugify_separator: _

post_excerpt

¥post_excerpt

9.2.0可选

¥9.2.0 {date}/{slug}

默认情况下，插件会将帖子摘录设为可选。如果帖子未定义摘录，则查看次数将包含整篇帖子。此设置可用于将帖子摘录设为必填项：

¥Use this setting to change the format string that is used when generating post URLs. You can freely combine placeholders, and join them with slashes or other characters:

plugins:
  - blog:
      post_excerpt: optional

plugins:
  - blog:
      post_excerpt: required

当需要文章摘录时，没有摘录分隔符的文章会引发错误。因此，当您想确保所有文章都定义了摘录时，此设置非常有用。

¥The following placeholders are available:

post_excerpt_max_authors

¥post_excerpt_max_authors

9.2.01

¥If you remove the date placeholder, make sure that post URLs don't collide with URLs of other pages hosted under the blog directory, as this leads to undefined behavior.

使用此设置可设置文章摘录中呈现的作者数量的上限。虽然每篇文章可能由多位作者撰写，但此设置允许将显示限制为仅显示几个甚至一位作者，或者在文章摘录中禁用作者：

¥9.2.0 1

plugins:
  - blog:
      post_excerpt_max_authors: 2

plugins:
  - blog:
      post_excerpt_max_authors: 0

这仅适用于视图中的帖子摘录。帖子始终会呈现所有作者。

¥Use this setting to set an upper bound for the number of categories included in post URLs if the categories placeholder is part of post_url_format and the post defines categories:

post_excerpt_max_categories

¥post_excerpt_max_categories

9.2.05

¥If more than one category is given, they are joined with / after slugifying.

使用此设置可设置帖子摘录中呈现的类别数量的上限。虽然每篇帖子可能被分配到多个类别，但此设置允许将显示限制为几个甚至单个类别，或者在帖子摘录中禁用类别：

¥9.2.0 pymdownx.slugs.slugify

plugins:
  - blog:
      post_excerpt_max_categories: 2

plugins:
  - blog:
      post_excerpt_max_categories: 0

这仅适用于视图中的帖子摘录。帖子始终会呈现所有类别。

¥Use this setting to change the function for generating URL-compatible slugs from post titles. By default, the slugify function from Python Markdown Extensions is used as follows:

post_excerpt_separator

¥post_excerpt_separator

9.2.0 <!-- 更多 -->

¥The default configuration is Unicode-aware and should produce good slugs for all languages. Of course, you can also provide a custom slugification function for more granular control.

使用此设置可设置插件在生成文章摘录时在文章内容中查找的分隔符。分隔符之前的所有内容均视为摘录的一部分：

¥9.2.0 -

plugins:
  - blog:
      post_excerpt_separator: <!-- more -->

通常的做法是使用 HTML 注释作为分隔符。

¥Use this setting to change the separator that is passed to the slugification function set as part of post_slugify. While the default is a hyphen, it can be set to any string, e.g., _:

post_readtime

¥post_readtime

9.2.0真

¥9.2.0 optional

使用此设置来控制插件是否应自动计算帖子的阅读时间，然后将其呈现在帖子摘录以及帖子本身中：

¥By default, the plugin makes post excerpts optional. When a post doesn't define an excerpt, views include the entire post. This setting can be used to make post excerpts required:

plugins:
  - blog:
      post_readtime: false

中文、日文和韩文字符

¥When post excerpts are required, posts without excerpt separators raise an error. Thus, this setting is useful when you want to make sure that all posts have excerpts defined.

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

¥9.2.0 1

post_readtime_words_per_minute

¥post_readtime_words_per_minute

9.2.0 265

¥Use this setting to set an upper bound for the number of authors rendered in post excerpts. While each post may be written by multiple authors, this setting allows to limit the display to just a few or even a single author, or disable authors in post excerpts:

使用此设置可更改计算文章阅读时间时读者每分钟预计阅读的字数。如果您想进行微调，请使用：

¥This only applies to post excerpts in views. Posts always render all authors.

plugins:
  - blog:
      post_readtime_words_per_minute: 300

每分钟265个单词的阅读时间被认为是成年人的平均阅读时间。

¥9.2.0 5

档案

¥Archive

存档页面有以下设置：

¥Use this setting to set an upper bound for the number of categories rendered in post excerpts. While each post may be assigned to multiple categories, this setting allows to limit the display to just a few or even a single category, or disable categories in post excerpts:

archive

¥archive

9.2.0真

¥This only applies to post excerpts in views. Posts always render all categories.

使用此设置可启用或禁用存档页面。存档页面会以相反的顺序显示特定时间间隔（例如年份、月份等）内的所有帖子。如果您想禁用存档页面，请使用：

¥9.2.0 <!-- more -->

plugins:
  - blog:
      archive: false

archive_name

¥archive_name

9.2.0

¥Use this setting to set the separator the plugin will look for in a post's content when generating post excerpts. All content before the separator is considered to be part of the excerpt:

使用此设置可更改插件添加到导航的存档部分的标题。如果省略此设置，则标题将来自翻译。如果您想更改它，请使用：

¥It is common practice to use an HTML comment as a separator.

plugins:
  - blog:
      archive_name: Archive

archive_date_format

¥archive_date_format

9.2.0年

¥9.2.0 true

使用此设置可更改存档页面标题的日期格式。格式字符串必须遵循babel的模式语法。一些常用的选择：

¥Use this setting to control whether the plugin should automatically compute the reading time of a post, which is then rendered in post excerpts, as well as in posts themselves:

plugins:
  - blog:
      archive_date_format: yyyy

plugins:
  - blog:
      archive_date_format: MMMM yyyy

请注意，根据网站语言的不同，其他语言的结果可能会有所不同。

¥Chinese, Japanese and Korean characters

archive_url_date_format

¥archive_url_date_format

9.2.0年

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

使用此设置可更改存档页面 URL 的日期格式。格式字符串必须遵循babel的模式语法，且不得包含空格。一些常用的格式：

¥9.2.0 265

plugins:
  - blog:
      archive_url_date_format: yyyy

plugins:
  - blog:
      archive_url_date_format: yyyy/MM

archive_url_format

¥archive_url_format

9.2.0存档/{日期}

¥Use this setting to change the number of words that a reader is expected to read per minute when computing the reading time of a post. If you want to fine-tune it, use:

使用此设置可更改生成存档页面 URL 时使用的格式字符串。您可以自由组合占位符，并使用斜杠或其他字符连接它们：

¥A reading time of 265 words per minute is considered to be the average reading time of an adult.

plugins:
  - blog:
      archive_url_format: "archive/{date}"

plugins:
  - blog:
      archive_url_format: "{date}"

可用的占位符如下：

¥The following settings are available for archive pages:

archive_pagination

¥archive_pagination

insiders-4.44.0真实

¥9.2.0 true

使用此设置可启用或禁用存档页面的分页功能。除非明确设置，否则此设置的值将从pagination继承。要禁用分页，请使用：

¥Use this setting to enable or disable archive pages. An archive page shows all posts for a specific interval (e.g. year, month, etc.) in reverse order. If you want to disable archive pages, use:

plugins:
  - blog:
      archive_pagination: false

archive_pagination_per_page

¥archive_pagination_per_page

insiders-4.44.0 10

¥9.2.0

使用此设置可更改每个存档页面呈现的帖子数量。除非明确设置，否则此设置的值继承自pagination_per_page 。要更改此设置，请使用：

¥Use this setting to change the title of the archive section the plugin adds to the navigation. If this setting is omitted, it's sourced from the translations. If you want to change it, use:

plugins:
  - blog:
      archive_pagination_per_page: 5

archive_toc

¥archive_toc

9.2.0错误

¥9.2.0 yyyy

使用此设置可利用目录在所有存档页面上显示文章标题。此设置的值继承自blog_toc ，除非明确设置。要更改此设置，请使用

¥Use this setting to change the date format used for archive page titles. The format string must adhere to babel's pattern syntax. Some popular choices:

plugins:
  - blog:
      archive_toc: true

类别

¥Categories

类别页面有以下设置：

¥Note that depending on the site language, results might look different for other languages.

categories

¥categories

9.2.0真

¥9.2.0 yyyy

使用此设置可启用或禁用分类页面。分类页面会按时间倒序显示特定分类下的所有文章。如果您想禁用分类页面，请使用：

¥Use this setting to change the date format used for archive page URLs. The format string must adhere to babel's pattern syntax and should not contain whitespace. Some popular choices:

plugins:
  - blog:
      categories: false

categories_name

¥categories_name

9.2.0

¥9.2.0 archive/{date}

使用此设置可更改插件添加到导航的类别部分的标题。如果省略此设置，则标题将来自翻译。如果您想更改它，请使用：

¥Use this setting to change the format string that is used when generating archive page URLs. You can freely combine placeholders, and join them with slashes or other characters:

plugins:
  - blog:
      categories_name: Categories

categories_url_format

¥categories_url_format

9.2.0类别/{slug}

¥The following placeholders are available:

使用此设置可更改生成类别页面 URL 时使用的格式字符串。您可以自由组合占位符，并使用斜线或其他字符将它们连接起来：

¥ insiders-4.44.0 true

plugins:
  - blog:
      categories_url_format: "category/{slug}"

plugins:
  - blog:
      categories_url_format: "{slug}"

可用的占位符如下：

¥Use this setting to enable or disable pagination for archive pages. The value of this setting is inherited from pagination, unless it's explicitly set. To disable pagination, use:

categories_slugify

¥categories_slugify

9.2.0 pymdownx.slugs.slugify

¥ insiders-4.44.0 10

使用此设置可更改从类别生成 URL 兼容 slug 的函数。默认情况下， Python Markdown 扩展中的slugify函数使用方式如下：

¥Use this setting to change the number of posts rendered per archive page. The value of this setting is inherited from pagination_per_page, unless it's explicitly set. To change it, use:

plugins:
  - blog:
      categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

默认配置支持 Unicode，应该能为所有语言生成良好的 slug。当然，您也可以提供自定义 slugification 函数，以实现更精细的控制。

¥9.2.0 false

categories_slugify_separator

¥categories_slugify_separator

9.2.0-

¥Use this setting to leverage the table of contents to display post titles on all archive pages. The value of this setting is inherited from blog_toc, unless it's explicitly set. To change it, use

使用此设置可以更改传递给categories_slugify函数的分隔符。默认值为连字符，但可以设置为任何字符串，例如_ ：

¥The following settings are available for category pages:

plugins:
  - blog:
      categories_slugify_separator: _

categories_sort_by

¥categories_sort_by

insiders-4.45.0 material.plugins.blog.view_name

¥9.2.0 true

使用此设置可指定用于对类别进行排序的自定义函数。例如，如果您想按类别包含的帖子数量对其进行排序，请使用以下配置：

¥Use this setting to enable or disable category pages. A category page shows all posts for a specific category in reverse chronological order. If you want to disable category pages, use:

plugins:
  - blog:
      categories_sort_by: !!python/name:material.plugins.blog.view_post_count

别忘了启用categories_sort_reverse 。你可以定义自己的比较函数，该函数必须返回排序时可以比较的内容，例如字符串或数字。

¥9.2.0

categories_sort_reverse

¥categories_sort_reverse

insiders-4.45.0 false

¥Use this setting to change the title of the category section the plugin adds to the navigation. If this setting is omitted, it's sourced from the translations. If you want to change it, use:

使用此设置可反转类别的排序顺序。默认情况下，类别按升序排列，但您可以按如下方式反转排序：

¥9.2.0 category/{slug}

plugins:
  - blog:
      categories_sort_reverse: true

categories_allowed

¥categories_allowed

9.2.0

¥Use this setting to change the format string that is used when generating category page URLs. You can freely combine placeholders, and join them with slashes or other characters:

该插件允许根据预定义列表检查类别，以便发现拼写错误或确保类别不会被随意添加。请使用以下命令指定要允许的类别：

¥The following placeholders are available:

plugins:
  - blog:
      categories_allowed:
        - Search
        - Performance

如果帖子引用了不属于此列表的类别，插件将停止构建。您可以使用categories 元数据属性将帖子分配到类别。

¥9.2.0 pymdownx.slugs.slugify

categories_pagination

¥categories_pagination

insiders-4.44.0真实

¥Use this setting to change the function for generating URL-compatible slugs from categories. By default, the slugify function from Python Markdown Extensions is used as follows:

使用此设置可启用或禁用类别页面的分页。除非明确设置，否则此设置的值将从pagination继承。要禁用分页，请使用：

¥The default configuration is Unicode-aware and should produce good slugs for all languages. Of course, you can also provide a custom slugification function for more granular control.

plugins:
  - blog:
      categories_pagination: false

categories_pagination_per_page

¥categories_pagination_per_page

insiders-4.44.0 10

¥9.2.0 -

使用此设置可更改每个类别页面呈现的帖子数量。除非明确设置，否则此设置的值继承自pagination_per_page 。要更改此设置，请使用：

¥Use this setting to change the separator that is passed to the slugification function set as part of categories_slugify. While the default is a hyphen, it can be set to any string, e.g., _:

plugins:
  - blog:
      categories_pagination_per_page: 5

categories_toc

¥categories_toc

9.2.0错误

¥ insiders-4.45.0 material.plugins.blog.view_name

使用此设置可利用目录在所有类别页面上显示文章标题。此设置的值继承自blog_toc ，除非明确设置。要更改此设置，请使用：

¥Use this setting to specify a custom function for sorting categories. For example, if you want to sort categories by the number of posts they contain, use the following configuration:

plugins:
  - blog:
      categories_toc: true

作者

¥Authors

作者可以使用以下设置：

¥Don't forget to enable categories_sort_reverse. You can define your own comparison function, which must return something that can be compared while sorting, i.e., a string or number.

authors

¥authors

9.2.0真

¥ insiders-4.45.0 false

使用此设置可启用或禁用帖子作者。如果启用此设置，插件将查找名为.authors.yml的文件，并在帖子和视图中呈现作者。使用以下命令禁用此行为：

¥Use this setting to reverse the order in which categories are sorted. By default, categories are sorted in ascending order, but you can reverse ordering as follows:

plugins:
  - blog:
      authors: false

authors_file

¥authors_file

9.2.0 {博客}/.authors.yml

¥9.2.0

使用此设置可以更改保存您文章作者信息的文件路径。通常情况下无需更改此设置，但如果需要，请使用：

¥The plugin allows to check categories against a predefined list, in order to catch typos or make sure that categories are not arbitrarily added. Specify the categories you want to allow with:

plugins:
  - blog:
      authors_file: "{blog}/.authors.yml"

可用的占位符如下：

¥The plugin stops the build if a post references a category that is not part of this list. Posts can be assigned to categories by using the categories metadata property.

提供的路径是从文档目录解析的。

¥ insiders-4.44.0 true

作者信息格式

¥Use this setting to enable or disable pagination for category pages. The value of this setting is inherited from pagination, unless it's explicitly set. To disable pagination, use:

.authors.yml文件必须遵循以下格式：

¥ insiders-4.44.0 10

.authors.yml
authors:
  <author>:
    name: string        # Author name
    description: string # Author description
    avatar: url         # Author avatar
    slug: url           # Author profile slug
    url: url            # Author website URL

请注意，必须将<author>设置为用于将作者与帖子关联的标识符，例如squidfunk这样的 GitHub 用户名。此标识符随后可用于帖子的authors元数据属性。支持多位作者。例如，请参阅我们博客中使用的.authors.yml 文件。

¥Use this setting to change the number of posts rendered per category page. The value of this setting is inherited from pagination_per_page, unless it's explicitly set. To change it, use:

authors_profiles

¥authors_profiles

insiders-4.46.0 false

¥9.2.0 false

使用此设置可启用或禁用自动生成的作者个人资料。作者个人资料会按时间倒序显示作者的所有帖子。您可以通过以下方式启用作者个人资料：

¥Use this setting to leverage the table of contents to display post titles on all category pages. The value of this setting is inherited from blog_toc, unless it's explicitly set. To change it, use:

plugins:
  - blog:
      authors_profiles: true

authors_profiles_name

¥authors_profiles_name

insiders-4.46.0

¥The following settings are available for authors:

使用此设置可更改插件添加到导航栏的作者部分的标题。如果省略此设置，则标题将来自翻译。如果您想更改它，请使用：

¥9.2.0 true

plugins:
  - blog:
      authors_profiles_name: Authors

authors_profiles_url_format

¥authors_profiles_url_format

insiders-4.46.0作者/{slug}

¥Use this setting to enable or disable post authors. If this setting is enabled, the plugin will look for a file named .authors.yml and render authors in posts and views. Disable this behavior with:

使用此设置可更改生成作者个人资料 URL 时使用的格式字符串。您可以自由组合占位符，并使用斜线或其他字符连接它们：

¥9.2.0 {blog}/.authors.yml

plugins:
  - blog:
      authors_profiles_url_format: "author/{slug}"

plugins:
  - blog:
      authors_profiles_url_format: "{slug}"

可用的占位符如下：

¥Use this setting to change the path of the file where the author information for your posts resides. It's normally not necessary to change this setting, but if you need to, use:

authors_profiles_pagination

¥authors_profiles_pagination

insiders-4.46.0真实

¥The following placeholders are available:

使用此设置可启用或禁用作者个人资料的分页功能。除非明确设置，否则此设置的值将从pagination继承。要禁用分页，请使用：

¥The provided path is resolved from the docs directory.

plugins:
  - blog:
      authors_profiles_pagination: false

authors_profiles_pagination_per_page

¥authors_profiles_pagination_per_page

insiders-4.46.0 10

¥Format of author information

使用此设置可更改每个存档页面呈现的帖子数量。除非明确设置，否则此设置的值继承自pagination_per_page 。要更改此设置，请使用：

¥The .authors.yml file must adhere to the following format:

plugins:
  - blog:
      authors_profiles_pagination_per_page: 5

authors_profiles_toc

¥authors_profiles_toc

insiders-4.46.0 false

¥Note that <author> must be set to an identifier for associating authors with posts, e.g., a GitHub username like squidfunk. This identifier can then be used in the authors metadata property of a post. Multiple authors are supported. As an example, see the .authors.yml file we're using for our blog.

使用此设置可利用目录在所有作者个人资料中显示文章标题。此设置的值继承自blog_toc ，除非明确设置。要更改它，请使用：

¥ insiders-4.46.0 false

plugins:
  - blog:
      authors_profiles_toc: true

分页

¥Pagination

以下设置可用于分页：

¥Use this setting to enable or disable automatically generated author profiles. An author profile shows all posts by an author in reverse chronological order. You can enable author profiles with:

pagination

¥pagination

9.2.0真

¥ insiders-4.46.0

使用此设置可在视图中启用或禁用分页功能。视图会生成按时间倒序显示文章或文章子集的页面。如果您要禁用分页，请使用：

¥Use this setting to change the title of the authors section the plugin adds to the navigation. If this setting is omitted, it's sourced from the translations. If you want to change it, use:

plugins:
  - blog:
      pagination: false

pagination_per_page

¥pagination_per_page

9.2.0 10

¥ insiders-4.46.0 author/{slug}

使用此设置可更改每页呈现的帖子数。如果您的帖子摘录较长，建议减少每页显示的帖子数：

¥Use this setting to change the format string that is used when generating author profile URLs. You can freely combine placeholders, and join them with slashes or other characters:

plugins:
  - blog:
      pagination_per_page: 5

pagination_url_format

¥pagination_url_format

9.2.0页/{页}

¥The following placeholders are available:

使用此设置可更改生成分页视图 URL 时使用的格式字符串。您可以自由组合占位符，并使用斜杠或其他字符将它们连接起来：

¥ insiders-4.46.0 true

plugins:
  - blog:
      pagination_url_format: "page/{page}"

plugins:
  - blog:
      pagination_url_format: "{page}"

可用的占位符如下：

¥Use this setting to enable or disable pagination for author profiles. The value of this setting is inherited from pagination, unless it's explicitly set. To disable pagination, use:

  • page – 页码

    ¥page – Page number

pagination_format

¥pagination_format

9.2.0 ~2~

¥ insiders-4.46.0 10

该插件使用paginate模块通过特殊语法生成分页标记。使用此设置可以自定义分页的构造方式。一些常用的选项：

¥Use this setting to change the number of posts rendered per archive page. The value of this setting is inherited from pagination_per_page, unless it's explicitly set. To change it, use:

plugins:
  - blog:
      pagination_format: "~2~"

plugins:
  - blog:
      pagination_format: "$link_first $link_previous ~2~ $link_next $link_last"

plugins:
  - blog:
      pagination_format: "$link_previous $page $link_next"

paginate支持以下占位符：

¥ insiders-4.46.0 false

  • $first_page$ first_page – 第一个可访问页面的数量

    ¥$first_page – Number of first reachable page

  • $last_page$ last_page – 最后可到达页面的数量

    ¥$last_page – Number of last reachable page

  • $page$ page – 当前选定的页码

    ¥$page – Number of currently selected page

  • $page_count$ page_count – 可访问页面的数量

    ¥$page_count – Number of reachable pages

  • $items_per_page$ items_per_page – 每页最大项目数

    ¥$items_per_page – Maximal number of items per page

  • $first_item$ first_item – 当前页面第一项的索引

    ¥$first_item – Index of first item on the current page

  • $last_item$ last_item – 当前页面最后一项的索引

    ¥$last_item – Index of last item on the current page

  • $item_count$ item_count – 商品总数

    ¥$item_count – Total number of items

  • $link_first$ link_first – 链接到第一页（除非在第一页）

    ¥$link_first – Link to first page (unless on first page)

  • $link_last$ link_last – 链接到最后一页（除非在最后一页）

    ¥$link_last – Link to last page (unless on last page)

  • $link_previous$ link_previous – 链接到上一页（除非在第一页）

    ¥$link_previous – Link to previous page (unless on first page)

  • $link_next$ link_next – 链接到下一页（除非在最后一页）

    ¥$link_next – Link to next page (unless on last page)

pagination_if_single_page

¥pagination_if_single_page

9.2.0错误

¥Use this setting to leverage the table of contents to display post titles on all author profiles. The value of this setting is inherited from blog_toc, unless it's explicitly set. To change it, use:

使用此设置来控制当视图仅包含单个页面时是否自动禁用分页。如果您希望始终呈现分页，请使用：

¥The following settings are available for pagination:

plugins:
  - blog:
      pagination_if_single_page: true

pagination_keep_content

¥pagination_keep_content

9.2.0错误

¥9.2.0 true

使用此设置可以启用或禁用内容持久化，即分页视图是否也显示其所在视图的内容。如果要启用此行为，请使用：

¥Use this setting to enable or disable pagination in views – generated pages that show posts or subsets of posts in reverse chronological order. If you want to disable pagination, use:

plugins:
  - blog:
      pagination_keep_content: true

草稿

¥Drafts

草稿可进行以下设置：

¥9.2.0 10

draft

¥draft

9.2.0错误

¥Use this setting to change the number of posts rendered per page. If you have rather long post excerpts, it can be a good idea to reduce the number of posts per page:

渲染草稿帖子在部署预览中很有用。使用此设置指定插件在构建项目时是否包含标记为草稿的帖子：

¥9.2.0 page/{page}

plugins:
  - blog:
      draft: true

plugins:
  - blog:
      draft: false

draft_on_serve

¥draft_on_serve

9.2.0真

¥Use this setting to change the format string that is used when generating paginated view URLs. You can freely combine placeholders, and join them with slashes or other characters:

使用此设置可控制插件在预览网站时是否包含标记为草稿的帖子。如果您不想在预览时包含草稿帖子，请使用：

¥The following placeholders are available:

plugins:
  - blog:
      draft_on_serve: false

draft_if_future_date

¥draft_if_future_date

9.2.0错误

¥9.2.0 ~2~

该插件可以自动将未来日期的帖子标记为草稿。如果日期超过今天，则在构建项目时会自动包含该帖子，除非明确标记为草稿：

¥The plugin uses the paginate module to generate the pagination markup using a special syntax. Use this setting to customize how pagination is constructed. Some popular choices:

plugins:
  - blog:
      draft_if_future_date: true

用法

¥Usage

元数据

¥Metadata

帖子可以定义一些元数据属性，用于指定插件如何呈现帖子、在哪些视图中集成帖子以及如何相互链接。每篇帖子的元数据都会根据一个模式进行验证，以便更快地发现语法错误。

¥The following placeholders are supported by paginate:

可用的属性如下：

¥9.2.0 false

authors

¥authors

9.2.0

¥Use this setting to control whether pagination should be automatically disabled when the view only consists of a single page. If you want to always render pagination, use:

使用此属性，通过提供在authors_file中定义的标识符列表，将文章与作者关联起来。如果无法解析作者，插件将终止并显示错误：

¥9.2.0 false

---
authors:
  - squidfunk # (1)!
---

# Post title
...

  1. 作者通过其标识符进行链接。例如，请参阅我们博客使用的.authors.yml 文件。

    ¥Authors are linked by using their identifiers. As an example, see the .authors.yml file we're using for our blog.

categories

¥categories

9.2.0

¥Use this setting to enable or disable persistence of content, i.e., if paginated views should also display the content of their containing view. If you want to enable this behavior, use:

使用此属性可将帖子与一个或多个类别关联，使帖子成为生成的类别页面的一部分。类别定义为字符串列表（允许使用空格）：

¥The following settings are available for drafts:

---
categories:
  - Search
  - Performance
---

# Post title
...

如果您想防止意外输入拼写错误而为帖子分配类别，您可以使用categories_allowed设置在mkdocs.yml中设置预定义的允许类别列表。

¥9.2.0 false

date

¥date

9.2.0

¥Rendering draft posts can be useful in deploy previews. Use this setting to specify whether the plugin should include posts marked as drafts when building your project:

使用此属性指定帖子的日期。请注意，此属性是必需的，这意味着如果未设置，构建将失败。您可以使用略有不同的语法来设置其他日期：

¥9.2.0 true

---
date: 2024-01-31
---

# Post title
...

---
date:
  created: 2024-01-31 # (1)!
  updated: 2024-02-01
---

# Post title
...

  1. 每个帖子都必须设置创建日期。

    ¥Each post must have a creation date set.

---
date:
  created: 2024-01-31
  my_custom_date: 2024-02-01 # (1)!
---

# Post title
...

  1. 博客插件会验证所有日期，并允许在模板中使用Babel的模式语法对其进行格式化。使用主题扩展时，作者可以向模板添加自定义日期。该请求最初来自#5733 。

支持以下日期格式：

¥Use this setting to control whether the plugin should include posts marked as drafts when previewing your site. If you don't wish to include draft posts when previewing, use:

  • 2024-01-31

    ¥2024-01-31

  • 2024-01-31T12:00:00

    ¥2024-01-31T12:00:00

draft

¥draft

9.2.0

¥9.2.0 false

使用此属性可将帖子标记为草稿。该插件允许在使用草稿设置构建项目时包含或排除标记为草稿的帖子。使用以下方法将帖子标记为草稿：

¥The plugin can automatically mark posts with future dates as drafts. When the date is past today, the post is automatically included when building your project, unless explicitly marked as draft:

---
draft: true
---

# Post title
...

pin

¥pin

insiders-4.53.0错误的

¥Posts can define a handful of metadata properties that specify how the plugin renders them, in which views they are integrated, and how they are linked to each other. The metadata of each post is validated against a schema to allow for a quicker discovery of syntax errors.

使用此属性可将帖子固定到视图顶部。如果固定了多篇帖子，则固定的帖子将按降序排列，并显示在所有其他帖子之前。使用以下方式固定帖子：

¥The following properties are available:

---
pin: true
---

# Post title
...

¥links

insiders-4.23.0

¥9.2.0

使用此属性定义在文章侧边栏中呈现的链接列表。该属性遵循与mkdocs.yml中的nav相同的语法，支持章节甚至锚点：

¥Use this property to associate a post with authors by providing a list of identifiers as defined in the authors_file. If an author can't be resolved, the plugin will terminate with an error:

---
links:
  - setup/setting-up-site-search.md
  - insiders/index.md
---

# Post title
...

---
links:
  - setup/setting-up-site-search.md
  - Insiders:
    - insiders/index.md
    - insiders/getting-started.md
---

# Post title
...

---
links:
  - plugins/search.md # (1)!
  - Insiders:
    - insiders/how-to-sponsor.md
    - insiders/getting-started.md#requirements
---

# Post title
...

  1. 如果链接定义了锚点，则插件会从链接页面解析锚点，并将锚点标题设置为副标题。

    ¥If a link defines an anchor, the plugin resolves the anchor from the linked page and sets the anchor title as a subtitle.

所有相关链接均从文档目录解析。

¥9.2.0

readtime

¥readtime

9.2.0

¥Use this property to associate a post with one or more categories, making the post a part of the generated category page. Categories are defined as a list of strings (whitespaces are allowed):

使用此属性可以明确设置帖子的阅读时间（以分钟为单位）。启用post_readtime后，插件会计算帖子的阅读时间，可以使用以下命令覆盖该时间：

¥If you want to prevent accidental typos assigning categories to posts, you can set a predefined list of allowed categories in mkdocs.yml by using the categories_allowed setting.

---
readtime: 15
---

# Post title
...

slug

¥slug

9.2.0

¥9.2.0

使用此属性可以明确设置帖子的 slug。默认情况下，帖子的 slug 由post_slugify函数根据帖子标题自动计算，可以使用以下命令覆盖：

¥Use this property to specify a post's date. Note that this property is required, which means the build fails when it's not set. Additional dates can be set by using a slightly different syntax:

---
slug: help-im-trapped-in-a-universe-factory
---

# Post title
...

Slugs 被传递给post_url_format 。

¥The blog plugin validates all dates and allows to format them with babel's pattern syntax in templates. When using theme extension, authors can add custom dates to templates.

缺少了什么吗？

¥This was first requested in #5733.

在设置博客或从其他博客框架迁移时，您可能会发现缺少某些功能——我们很乐意考虑将其添加到插件中！您可以发起讨论提问，或在我们的问题跟踪器上创建变更请求，以便我们了解该功能是否适合该插件。

¥The following date formats are supported:

  1. 视图是自动生成的页面，即博客的入口点，其中列出了所有最新帖子，以及存档和类别页面，其中按时间顺序通过元数据列出与其相关的所有帖子。↩