内置博客插件¶

博客插件使构建博客变得非常容易，无论是作为sidecar还是您的文档或作为主要内容。在插件运行期间，专注于您的内容完成所有繁重的工作，生成所有最新帖子的视图，[存档]和 [类别]页面，可配置[分页]等等。

客观的¶

工作原理¶

该插件扫描已配置的[“posts”目录][config.post_dir]以查找 `.md文件，从中自动生成分页视图¹。如果没有否则，插件会要求您的项目具有以下内容目录布局，并将为您创建任何缺失的目录或文件：

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

[blog目录][config.blog_dir]中的index.md文件是条目指向你的博客——一个按时间倒序列出所有帖子的分页视图订单。除此之外，该插件还支持自动创建[存档]和 category页面列出了某个时间间隔或类别的帖子子集。

[Post url][config.Post_url_format]是完全可配置的，无论是否您是否希望您的URL包含帖子的日期。始终呈现日期以项目的[站点语言]的区域设置显示。就像在其他静态博客框架、帖子可以用各种[元数据]进行注释，允许与其他[内置插件]轻松集成，例如 [社交]和[标签]插件。

帖子可以组织在嵌套文件夹中，目录布局适合您的根据特定需求，可以使用该材料的所有组件和语法 MkDocs提供，包括[警告]、[注释]、[代码块]， [内容选项卡]、[图表]、[图标]、[数学]等。

何时使用¶

如果你想在项目中添加一个博客，或者从另一个博客迁移 MkDocs的Material框架，因为它具有出色的技术写作能力功能，这个插件是一个不错的选择，因为它与许多其他内置插件：

Built-in meta plugin

元插件使将[元数据]应用于帖子子集变得容易，包括作者、标签、类别、草稿状态以及社交卡布局。

Simpler organization, categorization and management of post metadata
Built-in social plugin

社交插件会自动生成美观且可定制的内容每个帖子和页面的社交卡片，在社交媒体上作为预览显示。

Links to your blog render beautiful social cards when shared on social media
Built-in optimize plugin

优化插件自动识别并优化所有媒体文件通过使用压缩和转换在项目中引用技术。

Your blog loads faster as smaller images are served to your users
Built-in tags plugin

标签插件允许将帖子与页面一起分类项目，以提高其可发现性，并将帖子连接到您的文档。

Your documentation's tag system integrates with your blog

配置¶

与所有[内置插件]一样，开始使用博客插件是直截了当。只需将以下行添加到mkdocs.yml中，您就可以开始写你的第一篇文章：

plugins:
  - blog

博客插件内置于MkDocs的Material中，不需要安装。

导航¶

如果您的mkdocs.yml中没有配置站点导航，那么有无需更多操作。博客[存档]和[类别]页面将自动显示在自动生成的导航下方。

如果您确实定义了导航结构，则需要指定博客应该出现在哪里。创建一个带有索引的导航部分博客的页面]：

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

[存档]和[类别]页面将显示在该部分中博客部分页面下方的子部分。在这种情况下，他们会出现在index.md之后。“index.md”文件的路径必须匹配 [blog_dir][config.blog_dir]。这意味着您可以命名博客导航输入任何你喜欢的东西：“博客”或“新闻”，或者“提示”。

一般的¶

以下设置可用：

¶

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

plugins:
  - blog:
      enabled: false

¶

使用此设置更改您的博客在 [文档目录][mkdocs.docs_dir]。路径包含在生成的 URL作为所有帖子和视图的前缀。您可以通过以下方式进行更改：

Documentation + BlogBlog only

plugins:
  - blog:
      blog_dir: blog

plugins:
  - blog:
      blog_dir: .

提供的路径是从[docs目录][mkdocs.docs_dir]解析的。

¶

使用此设置可利用目录在中显示帖子标题意见。如果你的帖子摘录很长，这可能会很有用。如果你想要我要启用它，请使用：

plugins:
  - blog:
      blog_toc: true

贴子¶

以下设置可用于帖子：

¶

使用此设置更改帖子所在的文件夹。它是通常不需要更改此设置，但如果要重命名文件夹或更改其文件系统位置，使用：

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

请注意，[posts目录][config.post_dir]仅用于post 组织-它不包含在帖子URL中，因为它们是自动的并且由该插件轻松生成。

以下占位符可用：

blog – [blog directory][config.blog_dir]

提供的路径是从[docs目录][mkdocs.docs_dir]解析的。

¶

使用此设置可更改帖子的日期格式。此插件使用babel 以配置的[站点语言]呈现日期。你可以用babel [模式语法]或以下简码：

Monday, January 31, 2024January 31, 2024Jan 31, 20241/31/24

plugins:
  - blog:
      post_date_format: full

plugins:
  - blog:
      post_date_format: long

plugins:
  - blog:
      post_date_format: medium

plugins:
  - blog:
      post_date_format: short

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

¶

使用此设置可更改帖子URL中使用的日期格式。格式字符串必须遵循babel的[pattern语法]，并且不应包含空格。一些流行的选择：

blog/2024/01/31// blog/2024/01// blog/2024//

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][config.post_url_fformat]格式字符串。

¶

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

blog/2024// blog//

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

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

以下占位符可用：

categories – Post categories, slugified with [categories_slugify][config.categories_slugify]
date – Post date, formatted with [post_url_date_format][config.post_url_date_format]
slug – Post title, slugified with [post_slugify][config.post_slugify], or explicitly set via [slug][meta.slug] metadata property
file – Post filename without .md file extension

如果删除“日期”占位符，请确保帖子URL不会冲突其中其他页面的URL托管在[“blog”目录][config.blog_dir]下，因为这会导致未定义的行为。

¶

使用此设置为中包含的类别数量设置上限如果“类别”占位符是[“post_url_format”]的一部分，则发布url [config.post_url_format]，帖子定义了类别：

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

如果给出了多个类别，则在行贿后用“/”连接。

¶

使用此设置更改生成与URL兼容的slug的功能从帖子标题。默认情况下，'slugify函数 [Python Markdown扩展]的用法如下：

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

默认配置支持Unicode，应该能为所有人生成良好的slug 语言。当然，您还可以为以下对象提供自定义的slugif功能更精细的控制。

¶

使用此设置更改传递给slugif的分隔符函数集为[post_slugify]的一部分[config.post_slugify]。虽然默认是连字符，可以设置为任何字符串，例如“_”：

plugins:
  - blog:
      post_slugify_separator: _

¶

默认情况下，插件会制作[帖子摘录]（../setup/setup-a-blog.md#添加摘录）可选。当一篇帖子没有定义摘录时，视图包括整个帖子。此设置可用于制作所需的帖子摘录：

OptionalRequired

plugins:
  - blog:
      post_excerpt: optional

plugins:
  - blog:
      post_excerpt: required

当需要帖子摘录时，没有摘录分隔符的帖子会引发错误。因此，当您想确保所有帖子已定义摘录。

¶

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

Render up to 2 authorsDisable authors

plugins:
  - blog:
      post_excerpt_max_authors: 2

plugins:
  - blog:
      post_excerpt_max_authors: 0

这仅适用于观点中的帖子摘录。帖子总是呈现所有作者。

¶

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

Render up to 2 categoriesDisable categories

plugins:
  - blog:
      post_excerpt_max_categories: 2

plugins:
  - blog:
      post_excerpt_max_categories: 0

这仅适用于观点中的帖子摘录。帖子总是呈现所有类别。

¶

使用此设置设置插件将在帖子中查找的分隔符生成帖子摘录时的内容。所有内容__before _分隔符为被认为是摘录的一部分：

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

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

¶

使用此设置控制插件是否应自动计算帖子的阅读时间，然后以帖子摘录的形式呈现，以及发布自己：

plugins:
  - blog:
      post_readtime: false

汉字、日文和韩文

阅读时间计算目前不采用中文分词，考虑到日文和韩文字符。这意味着阅读用这些语言发帖的时间可能不准确。我们正在计划在未来增加支持。与此同时，请使用“阅读时间”` front matter属性用于设置读取时间。

¶

使用此设置更改读者应阅读的字数在计算帖子的阅读时间时，每分钟。如果你想微调它，使用：

plugins:
  - blog:
      post_readtime_words_per_minute: 300

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

档案¶

以下设置可用于存档页面：

¶

使用此设置启用或禁用存档页面。存档页面显示所有按相反顺序发布特定时间间隔（例如年、月等）的帖子。如果你要禁用存档页面，请使用：

plugins:
  - blog:
      archive: false

¶

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

plugins:
  - blog:
      archive_name: Archive

¶

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

2024January 2024

plugins:
  - blog:
      archive_date_format: yyyy

plugins:
  - blog:
      archive_date_format: MMMM yyyy

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

¶

使用此设置可更改用于存档页面URL的日期格式格式字符串必须遵循babel的[pattern语法]，并且不应包含空白。一些流行的选择：

blog/archive/2024/ blog/archive/2024/01/

plugins:
  - blog:
      archive_url_date_format: yyyy

plugins:
  - blog:
      archive_url_date_format: yyyy/MM

¶

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

blog/archive/2024/ blog/2024/

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

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

以下占位符可用：

date – Archive date, formatted with [archive_url_date_format][config.archive_url_date_format]

¶

使用此设置可启用或禁用存档页面的分页。价值此设置的值继承自[`pagination][config.pagination]，除非它是明确设置。要禁用分页，请使用：

plugins:
  - blog:
      archive_pagination: false

¶

使用此设置可更改每个存档页面呈现的帖子数量。这个此设置的值继承自[“pagination_per_page”] [config.pagion_per_page]，除非明确设置。要更改它，请使用：

plugins:
  - blog:
      archive_pagination_per_page: 5

¶

使用此设置可利用目录显示所有帖子的标题存档页面。此设置的值继承自[blog_toc] [config.blog_toc]，除非明确设置。要更改它，请使用

plugins:
  - blog:
      archive_toc: true

类别¶

以下设置可用于类别页面：

¶

使用此设置启用或禁用类别页面。类别页面显示所有按时间倒序排列特定类别的帖子。如果你想禁用类别页面，使用：

plugins:
  - blog:
      categories: false

¶

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

plugins:
  - blog:
      categories_name: Categories

¶

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

blog/category// blog//

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

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

以下占位符可用：

slug–类别，用[categories_slugify][config.categories_shugify]分隔

¶

使用此设置更改生成与URL兼容的slug的功能从类别。默认情况下，'slugify函数 [Python Markdown扩展]的用法如下：

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

默认配置支持Unicode，应该能为所有人生成良好的slug 语言。当然，您还可以为以下对象提供自定义的slugif功能更精细的控制。

¶

使用此设置更改传递给slugif的分隔符函数集为[类别_插件]的一部分[配置.类别_插件]。与…同时默认值是连字符，可以设置为任何字符串，例如“_”：

plugins:
  - blog:
      categories_slugify_separator: _

¶

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

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

别忘了启用[`categories_sort_reverse][config.categories_sort _reverse]。您可以定义自己的比较函数，该函数必须返回一些值可以在排序时进行比较，即字符串或数字。

¶

使用此设置可颠倒类别的排序顺序。By 默认情况下，类别按升序排序，但您可以颠倒顺序如下：

plugins:
  - blog:
      categories_sort_reverse: true

¶

该插件允许根据预定义列表检查类别，以便捕捉拼写错误或确保类别不是任意添加的。指定您希望允许的类别：

plugins:
  - blog:
      categories_allowed:
        - Search
        - Performance

如果帖子引用的类别不属于这个列表。可以使用[“类别”]将帖子分配到类别中 [meta.classes]元数据属性。

¶

使用此设置可启用或禁用类别页面的分页。价值此设置的值继承自[`pagination][config.pagination]，除非它是明确设置。要禁用分页，请使用：

plugins:
  - blog:
      categories_pagination: false

¶

使用此设置可更改每个类别页面呈现的帖子数量。这个此设置的值继承自[“pagination_per_page”] [config.pagion_per_page]，除非明确设置。要更改它，请使用：

plugins:
  - blog:
      categories_pagination_per_page: 5

¶

使用此设置可利用目录显示所有帖子的标题类别页面。此设置的值继承自[blog_toc] [config.blog_toc]，除非明确设置。要更改它，请使用：

plugins:
  - blog:
      categories_toc: true

作者¶

作者可以使用以下设置：

¶

使用此设置启用或禁用文章作者。如果启用了该设置，该插件将查找一个名为[.orges.yml][config.authors_file]的文件在帖子和视图中呈现作者。通过以下方式禁用此行为：

plugins:
  - blog:
      authors: false

¶

使用此设置可更改其中包含作者信息的文件的路径你的帖子驻留。通常不需要更改此设置，但如果您需要使用：

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

以下占位符可用：

blog–[blog`目录][config.blog_dir]

提供的路径是从[docs目录][mkdocs.docs_dir]解析的。

Format of author information

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

.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

请注意，“”必须设置为用于关联作者的标识符带有帖子，例如GitHub用户名“squidfunk”。此标识符可以然后在[作者][元作者]元数据属性中使用一篇帖子。支持多个作者。例如，请参见 [我们博客使用的.orges.yml文件][.orges.ymml]。

¶

使用此设置启用或禁用自动生成的作者配置文件。作者简介按时间倒序显示作者的所有帖子。您可以通过以下方式启用作者配置文件：

plugins:
  - blog:
      authors_profiles: true

¶

使用此设置更改插件添加到的作者部分的标题导航。如果省略此设置，则其来源于翻译。如果你想更改它，请使用：

plugins:
  - blog:
      authors_profiles_name: Authors

¶

使用此设置更改生成时使用的格式字符串作者配置文件URL。您可以自由组合占位符，并将其与斜线或其他字符：

blog/author// blog//

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

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

The following placeholders are available:

slug – 来自[`authors_file][config.authors_file]的作者段符或标识符
name – 来自[`authors_file][config.authors_file]的作者名称

¶

使用此设置可启用或禁用作者配置文件的分页。价值此设置的值继承自[`pagination][config.pagination]，除非它是明确设置。要禁用分页，请使用：

plugins:
  - blog:
      authors_profiles_pagination: false

¶

使用此设置可更改每个存档页面呈现的帖子数量。这个此设置的值继承自[“pagination_per_page”] [config.pagion_per_page]，除非明确设置。要更改它，请使用：

plugins:
  - blog:
      authors_profiles_pagination_per_page: 5

¶

使用此设置可利用目录显示所有帖子的标题作者简介。此设置的值继承自[blog_toc] [config.blog_toc]，除非明确设置。要更改它，请使用：

plugins:
  - blog:
      authors_profiles_toc: true

分页¶

以下设置可用于分页：

¶

使用此设置在视图生成的页面中启用或禁用分页按逆时间顺序显示帖子或帖子子集。如果你想要我要禁用分页，请使用：

plugins:
  - blog:
      pagination: false

¶

使用此设置可更改每页呈现的帖子数量。如果你有相当长的帖子摘录，减少帖子数量可能是个好主意每页：

plugins:
  - blog:
      pagination_per_page: 5

¶

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

blog/page/n/ blog/n/

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

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

The following placeholders are available:

page – Page number

¶

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

1 2 3 .. n1 2 3 .. n 1

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"

The following placeholders are supported by paginate:

$first_page – Number of first reachable page
$last_page – Number of last reachable page
$page – Number of currently selected page
$page_count – Number of reachable pages
$items_per_page – Maximal number of items per page
$first_item – Index of first item on the current page
$last_item – Index of last item on the current page
$item_count – Total number of items
$link_first – Link to first page (unless on first page)
$link_last – Link to last page (unless on last page)
$link_previous – Link to previous page (unless on first page)
$link_next – Link to next page (unless on last page)

¶

使用此设置可控制是否应自动禁用分页当视图仅由单个页面组成时。如果你想一直渲染分页，使用：

plugins:
  - blog:
      pagination_if_single_page: true

¶

使用此设置启用或禁用内容的持久性，即如果分页视图还应显示其包含的视图的内容。如果你愿意启用此行为，请使用：

plugins:
  - blog:
      pagination_keep_content: true

Drafts¶

以下设置可用于草稿：

¶

渲染[草稿帖子][元草稿]在部署预览中很有用。使用这个设置以指定插件在以下情况下是否应包含标记为草稿的帖子 [构建您的项目]：

Render draftsDon't render drafts

plugins:
  - blog:
      draft: true

plugins:
  - blog:
      draft: false

¶

使用此设置控制插件是否应包含标记为的帖子 [预览网站]时的草稿。如果你不想包括草稿帖子预览时，使用：

plugins:
  - blog:
      draft_on_serve: false

¶

该插件可以自动将带有未来日期的帖子标记为草稿。当日期已过今天，当 [构建你的项目]，除非明确标记为草稿：

plugins:
  - blog:
      draft_if_future_date: true

使用¶

元数据¶

帖子可以定义一些元数据属性，指定插件的方式呈现它们，在哪些视图中集成它们，以及它们如何链接到彼此。每个帖子的元数据都会根据模式进行验证，以允许更快地发现语法错误。

以下属性可用：

¶

使用此属性通过提供以下列表将帖子与[作者]相关联标识符如[`authors_file][config.authors_file]中所定义。如果A 无法解析作者，插件将终止并显示错误：

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

# Post title
...

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

¶

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

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

# Post title
...

如果你想防止为帖子分配类别时出现意外拼写错误，你可以使用以下命令在“mkdocs.yml”中设置预定义的允许类别列表 [`categories_allowed][config.categories_alowed]设置。

¶

使用此属性指定帖子的日期。注意，该属性是必需的，这意味着构建在未设置时失败。其他日期可以通过以下方式设置使用稍微不同的语法：

DateUpdate dateCustom date

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

# Post title
...

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

# Post title
...

Each post must have a creation date set.

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

# Post title
...

博客插件验证所有日期，并允许使用模板中的babel的[模式语法]。当使用主题扩展时，作者可以将自定义日期添加到模板中。

这是在#5733中首次提出的要求。

支持以下日期格式：

2024-01-31
2024-01-31T12:00:00

¶

使用此属性将帖子标记为草稿。该插件允许包含或使用[构建项目]时排除标记为草稿的帖子 [草稿][配置草稿]设置。将帖子标记为草稿：

---
draft: true
---

# Post title
...

¶

使用此属性将柱子固定到视图的顶部。如果有多个帖子固定后，固定的帖子按降序排列，出现在所有帖子之前其他帖子。在柱子上钉上：

---
pin: true
---

# Post title
...

¶

使用此属性定义在侧边栏中呈现的链接列表一篇帖子。该属性遵循与中的[nav][mkdocs.nav]相同的语法 mkdocs.yml，支持部分甚至锚点：

LinksLinks with sectionsLinks with anchors

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

如果链接定义了锚点，则插件会从以下位置解析锚点链接页面，并将锚点标题设置为[字幕]。

所有相关链接都是从[docs目录][mkdocs.docs_dir]解析的。

¶

使用此属性显式设置帖子的阅读时间（分钟）。什么时候？启用[post_readtime][config.post_readtime]后，插件将计算帖子的阅读时间，可以用以下命令覆盖：

---
readtime: 15
---

# Post title
...

¶

使用此属性可以显式设置帖子的slug。默认情况下，slug 帖子由[`post_slugify][config.post_sluglify]自动计算可以用以下命令覆盖帖子标题中的函数：

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

# Post title
...

Slugs are passed to [post_url_format][config.post_url_format].

缺少什么？

在设置博客或从其他博客框架迁移时，您可能会发现您缺少特定功能–我们很乐意考虑将其添加到插件中！你可以[展开讨论] 在我们的[问题跟踪器]上提出问题或创建[更改请求]，因此我们可以找出它是否适合该插件。

视图是自动生成的页面，即您的博客列出了所有最新帖子，以及[存档]和[类别] 通过[元数据]列出与其关联的所有帖子的页面时间顺序。 ↩