内置博客插件¶

该博客插件使得创建博客变得非常轻松，无论是作为您文档的附属品还是作为主要内容。您可以专注于内容创作，而插件则负责繁重的任务，包括生成所有最新文章的视图、归档和分类 页面、可配置的分页功能等等。

目标¶

如何工作¶

该插件会扫描已配置的[posts目录][config.post_dir]，查找.md文件，并据此自动生成分页视图¹。如果未进行其他配置，该插件会默认您的项目具有以下目录结构，并且会为您创建任何缺失的目录或文件：

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

位于 [blog目录][config.blog_dir] 中的index.md文件是您的博客的入口点——一个分页视图，按逆时间顺序列出所有文章。除此之外，该插件还支持自动创建归档和分类页面，这些页面会列出特定时间段或分类下的一组文章。

[文章 URL][config.post_url_format] 完全可自定义，无论您是否希望URL中包含帖子的日期。渲染后的日期始终根据您项目的站点语言的本地设置显示。与其他静态博客框架一样，帖子可以使用各种元数据进行注解，从而轻松与其他内置插件集成，例如社交和标签插件。

文章可以根据您的具体需求，使用适合的目录布局组织在嵌套文件夹中，并且可以利用 MkDocs-For-Material 主题提供的所有组件和语法，包括警告、注解、代码块、内容选项卡、图表、图标,、数学公式等更多功能。

何时使用它¶

如果您想为您的项目添加一个博客，或者因为其出色的技术写作能力而从另一个博客框架迁移到Material-for-MkDocs，那么这个插件是一个绝佳的选择，因为它能够与其他许多内置插件完美集成：

配置¶

与所有内置插件一样，使用博客插件入门非常简单。只需在mkdocs.yml文件中添加以下几行，您就可以开始撰写您的第一篇帖子了：

plugins:
  - blog

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

导航¶

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

如果您已经定义了导航结构，则需要指定博客应该在此结构中的哪个位置。为博客创建一个带有索引页面的导航部分：

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

归档和分类页面将作为博客部分中页面下方的子部分出现在该部分内。在这种情况下，它们将出现在index.md之后。index.md文件的路径必须与[blog_dir][config.blog_dir]相匹配。这意味着您可以为博客导航条目命名任何您喜欢的名称：“Blog”（博客）、“News”（新闻）或“Tips”（技巧）等。

概述¶

以下设置可供使用：

¶

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

plugins:
  - blog:
      enabled: false

¶

使用此设置来更改博客在[docs目录][mkdocs.docs_dir]中的位置路径。该路径将作为所有博客和视图的前缀包含在生成的URL中。您可以使用以下方式更改它：

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]仅用于组织帖子——它不会包含在帖子的URL中，因为这些URL是由本插件自动且方便地生成的。

以下占位符可用：

• blog – [blog directory][config.blog_dir]

The provided path is resolved from the [docs directory][mkdocs.docs_dir].

¶

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

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的模式语法，并且不应包含空格。一些常见的选择包括：

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_format]格式字符串中删除date占位符。

¶

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

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

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

以下占位符可用：

• categories – 帖子类别，使用[categories_slugify][config.categories_slugify]进行slug化（即生成URL友好的字符串）
• date – 帖子日期，使用[post_url_date_format][config.post_url_date_format]进行格式化
• slug – 帖子标题，使用[post_slugify][config.post_slugify]进行slug化，或者通过元数据属性[slug][meta.slug]明确设置
• file –帖子文件名（不包含.md文件扩展名）

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

¶

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

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

如果指定了多个类别，它们将在slug化之后使用/连接起来。

¶

使用此设置可以更改从帖子标题生成与URL兼容的slug的函数。默认情况下，将使用Python Markdown Extensions中的slugify函数，如下所示：

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

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

¶

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

plugins:
  - blog:
      post_slugify_separator: _

¶

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

plugins:
  - blog:
      post_excerpt: required

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.

¶

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:

plugins:
  - blog:
      post_excerpt_max_authors: 2

plugins:
  - blog:
      post_excerpt_max_authors: 0

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

¶

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:

plugins:
  - blog:
      post_excerpt_max_categories: 2

plugins:
  - blog:
      post_excerpt_max_categories: 0

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

¶

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:

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

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

¶

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

¶

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:

plugins:
  - blog:
      post_readtime_words_per_minute: 300

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

Archive¶

The following settings are available for archive pages:

¶

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

¶

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

¶

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

plugins:
  - blog:
      archive_date_format: MMMM yyyy

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

¶

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

plugins:
  - blog:
      archive_url_date_format: yyyy/MM

¶

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:
      archive_url_format: "archive/{date}"

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

The following placeholders are available:

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

¶

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

plugins:
  - blog:
      archive_pagination: false

¶

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

plugins:
  - blog:
      archive_pagination_per_page: 5

¶

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] [config.blog_toc], unless it's explicitly set. To change it, use

plugins:
  - blog:
      archive_toc: true

Categories¶

The following settings are available for category pages:

¶

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

plugins:
  - blog:
      categories_name: Categories

¶

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:

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

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

The following placeholders are available:

• slug – Category, slugified with [categories_slugify][config.categories_slugify]

¶

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:

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

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.

¶

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

plugins:
  - blog:
      categories_slugify_separator: _

¶

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_sort_by: !!python/name:material.plugins.blog.view_post_count

Don't forget to enable [categories_sort_reverse][config.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.

¶

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

¶

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:
      categories_allowed:
        - Search
        - Performance

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] [meta.categories] metadata property.

¶

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

plugins:
  - blog:
      categories_pagination: false

¶

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

plugins:
  - blog:
      categories_pagination_per_page: 5

¶

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] [config.blog_toc], unless it's explicitly set. To change it, use:

plugins:
  - blog:
      categories_toc: true

Authors¶

The following settings are available for authors:

¶

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

plugins:
  - blog:
      authors: false

¶

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:

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

The following placeholders are available:

• blog – [blog directory][config.blog_dir]

The provided path is resolved from the [docs directory][mkdocs.docs_dir].

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

¶

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:

plugins:
  - blog:
      authors_profiles: true

¶

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

¶

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:
      authors_profiles_url_format: "author/{slug}"

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

The following placeholders are available:

• slug – Author slug or identifier from [authors_file][config.authors_file]
• name – Author name from [authors_file][config.authors_file]

¶

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

plugins:
  - blog:
      authors_profiles_pagination: false

¶

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

plugins:
  - blog:
      authors_profiles_pagination_per_page: 5

¶

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] [config.blog_toc], unless it's explicitly set. To change it, use:

plugins:
  - blog:
      authors_profiles_toc: true

Pagination¶

The following settings are available for pagination:

¶

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

¶

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:

plugins:
  - blog:
      pagination_per_page: 5

¶

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:

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

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

The following placeholders are available:

• page – Page number

¶

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

¶

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:

plugins:
  - blog:
      pagination_if_single_page: true

¶

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:

plugins:
  - blog:
      pagination_keep_content: true

Drafts¶

The following settings are available for drafts:

¶

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

plugins:
  - blog:
      draft: true

plugins:
  - blog:
      draft: false

¶

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:

plugins:
  - blog:
      draft_on_serve: 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:

plugins:
  - blog:
      draft_if_future_date: true

Usage¶

Metadata¶

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:

¶

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

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

# Post title
...

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

¶

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

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

# Post title
...

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][config.categories_allowed] setting.

¶

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:

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

# Post title
...

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

# Post title
...

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

# Post title
...

The following date formats are supported:

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

¶

Use this property to mark a post as draft. The plugin allows to include or exclude posts marked as drafts when building your project using the [draft][config.draft] setting. Mark a post as draft with:

---
draft: true
---

# Post title
...

¶

Use this property to pin a post to the top of a view. In case multiple posts are pinned, the pinned posts are sorted by descending order and appear before all other posts. Pin a post with:

---
pin: true
---

# Post title
...

¶

Use this property to define a list of links that are rendered in the sidebar of a post. The property follows the same syntax as [nav][mkdocs.nav] in mkdocs.yml, supporting sections and even 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
...

All relative links are resolved from the [docs directory][mkdocs.docs_dir].

¶

Use this property to explicitly set the reading time of a post in minutes. When [post_readtime][config.post_readtime] is enabled, the plugin computes the reading time of a post, which can be overridden with:

---
readtime: 15
---

# Post title
...

¶

Use this property to explicitly set the slug of a post. By default, the slug of a post is automatically computed by the [post_slugify][config.post_slugify] function from the post's title, which can be overridden with:

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

# Post title
...

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

参考¶

• https://github.com/squidfunk/mkdocs-material/blob/master/docs/plugins/blog.md