Skip to content

设置一个博客

使用 MkDocs 的 Material 主题非常容易构建一个博客,可以作为文档的附属品或独立存在。在引擎自动完成所有繁重的工作,自动生成归档分类索引,文章链接,可配置的分页等功能的同时,你可以专注于内容创作。


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

配置

内置博客插件

9.2.0b0 · 插件 · 实验性功能

内置博客插件支持从包含日期和其他结构化数据的文章文件夹构建博客。首先,在 mkdocs.yml 文件中添加以下行:

plugins:
  - blog

如果你需要同时构建包含和不包含 Insiders 的文档,请参考内置插件部分了解共享配置如何实现。

默认情况下,内置博客插件假设你的博客位于文档的 blog 子文件夹中(可以进行配置)。接下来,你需要创建以下结构:

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

由于内置博客插件会自动生成归档分类索引,它需要知道在导航栏中添加这些内容的位置。因此,请确保在 mkdocs.yml 文件中添加一个 blog/index.md 文件:

nav:
  - Blog:
      - blog/index.md # (1)!
  1. 在这个文件中,你可以指定博客的标题,内置博客插件会读取并使用它:

    # Blog
    

以下配置选项可用:

enabled

默认值:true – 此选项指定在构建项目时是否启用插件。如果你想加快本地构建速度,可以使用一个环境变量

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

blog_dir

默认值:blog – 此选项指定你的文章和元数据所在的文件夹。文件夹的名称也将作为生成的 URL 的前缀,包含在所有与博客相关的页面中。如果你想构建一个独立的博客,请将其更改为 .

plugins:
    - blog:
        blog_dir: blog
plugins:
    - blog:
        blog_dir: .

路径必须相对于 docs_dir 定义。

blog_toc

默认值:false – 此选项指定索引是否在右侧包含一个包含所有文章标题的目录作为概览:

plugins:
  - blog:
      blog_toc: true

注意,除非显式定义了这些设置,否则此设置也将用作 archive_toccategories_toc 的默认值。

内置博客插件有数十个选项,允许进行高级配置。建议开始撰写第一篇文章,然后稍后回到这里进行输出的微调。


文章

以下配置选项适用于文章:

post_date_format

默认值:long – 此选项指定渲染文章时使用的日期格式。在内部,内置博客插件利用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

请注意,根据站点语言的不同,格式可能在其他语言中有所不同。此外,Babel支持一种模式语法,允许自定义格式。

post_url_date_format

默认值:yyyy/MM/dd – 此选项指定在文章的 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

如果你想完全排除日期,例如当你的博客主要包含长青内容时,可以从格式字符串中删除 date 占位符(参见下面的示例)。

post_url_format

默认值:{date}/{slug} – 此选项指定用于文章 URL 的格式字符串。目前支持以下占位符:

  • categories – 使用文章的分类[categories]的 slug 替换。

  • date – 使用文章的日期替换,日期格式由post_url_date_format配置。

  • slug – 使用从文章标题生成的 slug 替换。

  • file – 使用文章的文件名替换。

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

如果删除了 date 占位符,请确保文章 URL 不与添加到博客部分的其他页面的 URL 冲突,因为这会导致未定义的行为。

post_url_max_categories

默认值:1 – 此选项指定如果[post_url_format][post slugs]中包含 categories 占位符,则在 URL 中包含的分类数。如果一篇文章分配给多个分类,则它们以 / 连接:

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

post_slugify

默认值:headerid.slugify – 此选项指定用于从文章标题生成 URL 兼容 slug 的函数。Python Markdown Extensions 提供了几个支持 Unicode 的 slug 函数,适用于非 ASCII 语言:

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

post_slugify_separator

默认值:- – 此选项指定 slug 函数使用的分隔符。默认情况下,使用连字符,但可以更改为任何字符串,包括空字符串:

plugins:
  - blog:
      post_slugify_separator: "-"

post_excerpt

默认值:optional – 此选项指定在生成索引时,内置博客插件是否将文章摘要[post excerpts]视为可选或必需的。如果要求摘要,如果文章没有定义摘要,插件将以错误终止:

plugins:
    - blog:
        post_excerpt: optional
plugins:
    - blog:
        post_excerpt: required

post_excerpt_max_authors

默认值:1 – 此选项指定在文章摘要中呈现的作者数量。尽管每篇文章可能由多个作者撰写,但此设置允许限制显示为几个或仅一个作者,或者在摘要中完全禁用作者:

plugins:
    - blog:
        post_excerpt_max_authors: 2
plugins:
    - blog:
        post_excerpt_max_authors: 0

post_excerpt_max_categories

默认值:5 – 此选项指定在文章摘要中呈现的分类数量。尽管每篇文章可能分配给多个分类,但可以通过指示内置博客插件仅显示前 n 个分类来使其简短和简洁:

plugins:
    - blog:
        post_excerpt_max_categories: 2
plugins:
    - blog:
        post_excerpt_max_categories: 0

post_excerpt_separator

默认值:<!-- more --> – 此选项指定内置博客插件在生成文章摘要[post excerpts]时在文章内容中查找的分隔符。分隔符之后的所有内容都不被视为摘要的一部分。

post_readtime

默认值:true – 此选项指定内置博客插件是否应自动计算文章的阅读时间,并在文章摘要以及文章本身中显示。如果要禁用阅读时间计算,请添加以下设置:

plugins:
  - blog:
      post_readtime: false

post_readtime_words_per_minute

默认值:265 – 此选项指定计算文章阅读时间时,读者每分钟阅读的单词数。如果您觉得估计不太准确,可以使用以下设置微调阅读时间计算:

plugins:
  - blog:
      post_readtime_words_per_minute: 265

存档

以下是用于生成存档索引的配置选项:

archive

默认值:true – 此选项指定内置博客插件是否应生成存档索引。存档索引以逆时间顺序显示指定时间间隔(例如年份、月份等)的所有文章。如果要禁用存档索引生成,请添加以下设置:

plugins:
  - blog:
      archive: false

archive_name

默认值:自动设置 – 此选项指定内置博客插件将生成并添加到导航中的存档部分的标题。如果省略此设置,将从翻译中获取,如果没有翻译,则回退到英文。可以使用以下设置进行更改:

plugins:
  - blog:
      archive_name: 存档

archive_date_format

默认值:yyyy – 此选项指定在渲染存档索引时使用的日期格式。格式字符串必须符合Babel模式语法。常用设置有:

plugins:
    - blog:
        archive_date_format: yyyy
plugins:
    - blog:
        archive_date_format: MMMM yyyy

archive_url_date_format

默认值:yyyy – 此选项指定存档索引 URL 中使用的日期格式。格式字符串必须符合Babel模式语法。以下是一些示例:

plugins:
    - blog:
        archive_url_date_format: yyyy
plugins:
    - blog:
        archive_url_date_format: yyyy/MM

archive_url_format

默认值:archive/{date} – 此选项指定存档索引 URL 的格式字符串,可用于本地化 URL:

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

archive_toc

默认值:false – 此选项指定存档索引是否包含右侧的带有所有文章标题的目录作为概览:

plugins:
  - blog:
      archive_toc: true

分类

以下是用于生成分类索引的配置选项:

categories

默认值:true – 此选项指定内置博客插件是否应生成分类索引。分类索引以逆时间顺序显示特定分类的所有文章。如果要禁用分类索引生成,请添加以下设置:

plugins:
  - blog:
      categories: false

categories_name

默认值:自动设置 – 此选项指定内置博客插件将生成并添加到导航中的分类部分的标题。如果省略此设置,将从翻译中获取,如果没有翻译,则回退到英文。可以使用以下设置进行更改:

plugins:
  - blog:
      categories_name: 分类

categories_url_format

默认值:category/{slug} – 此选项指定分类索引 URL 的格式字符串,可用于本地化 URL:

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

categories_slugify

默认值:headerid.slugify – 此选项指定用于从分类生成 URL 兼容的 slug 的函数。Python Markdown Extensions 提供了几个支持 Unicode 的 slug 函数,适用于非 ASCII 语言:

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

categories_slugify_separator

默认值:- – 此选项指定 slug 函数使用的分隔符。默认情况下,使用连字符,但可以更改为任何字符串,包括空字符串:

plugins:
  - blog:
      categories_slugify_separator: "-"

categories_allowed

默认值: – 此选项指定允许在文章中使用的分类。如果省略此设置,内置博客插件将不会检查分类名称。可以使用此选项定义分类列表以捕获拼写错误:

plugins:
  - blog:
      categories_allowed:
        - General
        - Search
        - Performance

categories_toc

默认值:false – 此选项指定分类索引是否包含右侧的带有所有文章标题的目录作为概览:

plugins:
  - blog:
      categories_toc: true

分页

以下是用于索引分页的配置选项:

pagination

默认值:true – 此选项指定内置博客插件是否应对索引进行分页。索引以逆时间顺序显示所有文章,可能会很多。如果要禁用索引分页,请添加以下设置:

plugins:
  - blog:
      pagination: false

pagination_per_page

默认值:10 – 此选项指定在单个索引页面上呈现的文章数量。如果找到更多的文章,它们将分配到第 2 页,依此类推。如果文章摘要很长,可能需要减少每页的文章数量:

plugins:
  - blog:
      pagination_per_page: 5

pagination_url_format

默认值:page/{page} – 此选项指定分页索引 URL 的格式字符串,可用于本地化 URL:

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

pagination_template

默认值:~2~ – 此选项指定提供给paginate模块的格式字符串,用于自定义分页的构建方式。常见的选择有:

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

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_keep_content

默认值:false – 此选项指定分页索引页面是否应继承索引页面(即blog/index.md)的自定义内容:

plugins:
  - blog:
      pagination_keep_content: true

作者

以下是有关作者信息的配置选项:

authors

默认值:true – 此选项指定内置博客插件是否应生成作者信息。如果启用此选项,插件将在名为.authors.yml的文件中查找作者,并在索引和文章中包含作者信息。如果要禁用此行为,请添加以下设置:

plugins:
  - blog:
      authors: false

authors_file

默认值:.authors.yml – 此选项指定包含文章作者的文件的名称。默认设置假定文件名为.authors.yml(注意开头的.):

plugins:
  - blog:
      authors_file: .authors.yml

路径必须相对于[blog_dir][可以配置]。还请参阅添加作者部分。

草稿

以下是草稿的配置选项:

draft

默认值:false – 此选项指定内置博客插件在构建站点时是否应包括标记为草稿的文章。在部署预览中包括草稿文章可能是有意义的,这也是为什么它存在的原因:

plugins:
    - blog:
        draft: true
plugins:
    - blog:
        draft: false

draft_on_serve

默认值:true – 此选项指定在使用mkdocs serve预览站点时,是否应包括标记为草稿的文章。默认情况下,预览时会渲染草稿,但在构建站点时会跳过它们:

plugins:
  - blog:
      draft_on_serve: true

draft_if_future_date

默认值:false – 此选项指定内置博客插件是否应将具有未来日期的文章标记为草稿。当日期超过当前日期时,文章会自动取消标记,并在构建站点时包括它们:

plugins:
  - blog:
      draft_if_future_date: true

RSS

仅赞助商 · insiders-4.23.0 · 插件

内置博客插件RSS 插件无缝集成,后者提供了一种简单的方法向您的博客(或整个文档)添加 RSS 订阅。使用pip安装它:

pip install mkdocs-rss-plugin

然后,在mkdocs.yml中添加以下行:

plugins:
  - rss:
      match_path: blog/posts/.* # (1)!
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags # (2)!
  1. RSS 插件允许过滤要包含在订阅中的 URL。在此示例中,只有博客文章将包含在订阅中。

  2. 如果要在订阅中包括文章的分类和标签,请使用以下行添加它们:

    plugins:
      - rss:
          categories:
            - categories
            - tags
    

支持以下配置选项:

enabled

默认值:true – 此选项指定在构建项目时是否启用该插件。如果要加快本地构建速度,可以使用环境变量:

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

match_path

默认值:.* – 此选项指定应包含在订阅中的页面。例如,要仅在订阅中包含博客文章,请使用以下正则表达式:

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

date_from_meta

默认值: – 此选项指定应将哪个前置数据属性用作订阅中页面的创建日期。建议使用date属性:

plugins:
  - rss:
      date_from_meta:
      as_creation: date

categories

默认值: – 此选项指定应作为订阅的一部分使用的前置数据属性作为分类。如果使用了分类标签,请使用以下行添加它们:

plugins:
  - rss:
      categories:
        - categories
        - tags

comments_path

默认值: – 此选项指定可以找到帖子或页面评论的锚点。如果已集成评论系统,请添加以下行:

plugins:
  - rss:
      comments_path: "#__comments"

Material for MkDocs 将自动为您的站点添加必要的元数据,以使 RSS 订阅在浏览器和订阅阅读器中可发现。请注意,RSS 插件还提供其他几个配置选项。有关更多信息,请参阅文档

使用方法

撰写第一篇文章

在成功设置内置博客插件之后,现在是时候撰写第一篇文章了。插件不假设任何特定的目录结构,因此您可以完全自由地组织文章,只要它们都位于posts目录中即可:

.
├─ docs/
  └─ blog/
     ├─ posts/
       └─ hello-world.md # (1)!
     └─ index.md
└─ mkdocs.yml
  1. 如果您想以不同的方式排列文章,可以自由选择。URL 是根据[post_url_format][文章别名]、文章的标题和日期构建的,与它们在posts目录中的组织方式无关。

创建一个名为hello-world.md的新文件,并添加以下行:

---
draft: true # (1)!
date: 2022-01-31 # (2)!
categories:
  - Hello
  - World
---
# Hello world!
  1. 如果将文章标记为草稿,则在索引页面上的文章日期旁边会出现红色标记。构建站点时,草稿不会包含在输出中。可以更改此行为,例如在构建部署预览时渲染草稿。

  2. 您可以使用date_updated来指示您更新博客文章的时间。日期将作为侧边栏的一部分呈现。

当您启动实时预览服务器时,您将看到您的第一篇文章!您还会意识到,自动生成了归档分类索引。

添加摘要

博客索引以及归档分类索引可以列出每篇文章的全部内容,也可以列出文章的摘要。通过在文章的前几段之后添加<!-- more -->分隔符,可以创建摘要:

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

内置博客插件生成所有索引时,会自动提取摘要分隔符之前的内容,使用户在决定是否阅读全文之前就可以开始阅读文章。

添加作者

为了给您的文章增添更多个性化,您可以将每篇文章与一个或多个作者关联起来。首先,在博客目录中创建.authors.yml文件,并添加一个作者:

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

.authors.yml文件将每个作者与一个标识符(在本示例中为squidfunk)关联起来,然后可以在文章中使用这些标识符。每个作者都可以使用以下属性:

name

默认值: · 必填 – 此属性必须为作者定义一个名称。名称将在每篇文章的左侧边栏中作为作者信息的一部分显示。

description

默认值: · 必填 – 此属性可用于为作者添加简短的描述,例如作者的角色、职业或任何其他标题。

avatar

默认值: · 必填 – 此属性必须指向有效的图像 URL(内部或外部),并作为文章和摘要中的作者头像。

现在,您可以通过在 Markdown 文件的前置数据中的authors属性中引用它们的标识符,将一个或多个作者分配给一篇文章。对于每个作者,都会在每篇文章的左侧边栏以及索引页面上的文章摘要中呈现一个小型个人资料:

---
date: 2022-01-31
authors:
  - squidfunk
    ...
---
# Hello world!

添加分类

分类是将您的文章按主题进行分组的绝佳方法,从而在专门的索引页面上进行组织。这样,对特定主题感兴趣的用户可以浏览您关于该主题的所有文章。确保启用了分类并将其添加到前置数据的categories属性中:

---
date: 2022-01-31
categories:
  - Hello
  - World
---
# Hello world!

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

添加标签

除了分类之外,内置博客插件还与内置标签插件集成。如果在前置数据的tags属性中添加标签,该标签将链接到标签索引

---
date: 2022-01-31
tags:
  - Foo
  - Bar
---
# Hello world!

与往常一样,标签将在主标题上方呈现,并且如果配置了,文章将在标签索引页面上链接。请注意,与页面一样,文章仅与其标题链接。

添加相关链接

仅赞助商 · insiders-4.23.0 · 实验性功能

相关链接提供了一种在文章中突出显示“进一步阅读”部分的完美方法,该部分包含在左侧边栏中,并引导用户到您文档的其他目标。使用前置数据的links属性将相关链接添加到文章中:

---
date: 2022-01-31
links:
  - setup/setting-up-site-search.md#built-in-search-plugin
  - insiders/index.md#how-to-become-a-sponsor
---
# Hello world!

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

---
date: 2022-01-31
links:
  - setup/setting-up-site-search.md#built-in-search-plugin
  - insiders/index.md#how-to-become-a-sponsor
  - 嵌套部分:
      - 外部链接: https://example.com
      - setup/setting-up-site-search.md
---
# Hello world!

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

请注意,所有链接必须相对于[docs_dir][文档目录],就像nav设置一样。

从文章链接到其他文章和页面

虽然[文章 URL][文章别名]是动态计算的,但内置博客插件确保所有从文章到其他文章和文章资产的链接都是正确的。如果要链接到一篇文章,只需使用 Markdown 文件的路径作为链接引用(链接必须是相对路径):

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

从一篇文章链接到页面(例如索引)时,遵循相同的方法:

[博客](../index.md)

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

设置阅读时间

启用时,readtime软件包用于计算每篇文章的预计阅读时间,该时间将作为文章和文章摘要的一部分呈现。现在,许多博客显示阅读时间,因此内置博客插件也提供了此功能。

然而,有时计算出的阅读时间可能不准确,或者导致奇怪和不愉快的数字。因此,可以通过为文章的前置数据readtime属性显式设置阅读时间来覆盖它:

---
date: 2022-01-31
readtime: 15
---
# Hello world!

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

设置默认值

如果有很多文章,为每篇文章定义上述所有内容可能会感到冗余。幸运的是,[内置元数据插件]允许为每个文件夹设置默认的前置数据属性。您可以按类别或作者对文章进行分组,并在.meta.yml文件中设置常见属性:

.
├─ docs/
  └─ blog/
     ├─ posts/
     ├─ .meta.yml # (1)!
     └─ index.md
└─ mkdocs.yml
  1. 如前所述,您还可以将.meta.yml文件放在posts目录的嵌套文件夹中。该文件可以定义所有在文章中有效的前置数据属性,例如:
authors:
  - squidfunk
categories:
  - Hello
  - World

请注意,顺序很重要 - [内置元数据插件]必须在mkdocs.yml中的博客插件之前定义,以便所有设置的默认值都能被内置博客插件正确获取:

plugins:
  - meta
  - blog

.meta.yml文件中的列表和字典将与文章中定义的值合并和去重,这意味着您可以在.meta.yml中定义常见属性,然后为每篇文章添加特定的属性或覆盖。

添加页面

除了文章,您还可以通过在mkdocs.ymlnav部分中列出页面来向博客添加静态页面。生成的所有索引都将包含在最后指定的页面之后。例如,要添加一个关于博客作者的页面,请将以下内容添加到mkdocs.yml中:

nav:
  - 博客:
      - blog/index.md
      - blog/authors.md
        ...

自定义

自定义索引页面

仅赞助商 · insiders-4.24.0 · 实验性功能

如果您想要向自动生成的归档分类索引中添加自定义内容,例如在文章列表之前添加类别描述,您可以手动在与内置博客插件创建它的位置相同的位置创建类别页面:

.
├─ docs/
  └─ blog/
     ├─ category/
       └─ hello.md # (1)!
     ├─ posts/
     └─ index.md
└─ mkdocs.yml
  1. 最简单的方法是首先将类别添加到博客文章中,然后获取由内置博客插件生成的 URL,并在[blog_dir][此处可配置]文件夹中的相应位置创建文件。

请注意,所示的目录列表基于默认配置。如果您为以下选项指定了不同的值,请确保相应地调整路径:

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

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

自动附加属于该类别的所有文章摘要。

覆盖模板

内置博客插件是基于 Material for MkDocs 构建的,这意味着您可以像通常那样使用主题扩展来覆盖用于博客的所有模板。

内置博客插件添加了以下模板: