设置博客¶

Material for MkDocs 使得构建博客变得非常简单，无论是作为文档的附属部分还是独立的博客。专注于您的内容，而引擎会处理所有繁重的工作，自动生成 archive 和 category 索引、可配置的 pagination 等等。

查看我们的 blog，它是使用新的 built-in blog plugin 创建的！

配置¶

内置博客插件¶

9.2.0 create-blog

内置博客插件支持从一个包含带有日期和其他结构化数据的文章的文件夹构建博客。首先，将以下行添加到 mkdocs.yml 中：

plugins:
  - blog

如果您的 mkdocs.yml 中没有导航 (nav) 定义，那么您无需做其他操作，因为博客插件会自动添加导航。如果您已经定义了导航，则只需将 博客索引页面 添加到其中即可。您不需要也不应该添加单独的博客文章。例如：

nav:
  - index.md
  - Blog:
    - blog/index.md

有关所有设置的列表，请查阅 plugin documentation。

RSS¶

9.2.0 rss

内置博客插件与 RSS plugin 无缝集成，提供了一种简单的方法来为您的博客（或整个文档）添加 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. 如果您希望在源中包含文章的类别以及标签，请在此处同时添加 categories 和 tags。

支持以下配置选项：

enabled

true 此选项指定在构建项目时插件是否启用。如果您希望加快本地构建速度，可以使用 environment variable：

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

此选项指定哪些前置属性用作源的一部分的类别。如果您使用 categories 和 tags，请使用以下行同时添加两者：

plugins:
  - rss:
      categories:
        - categories
        - tags

comments_path

此选项指定可以找到文章或页面评论的锚点。如果您集成了 comment system，请添加以下行：

plugins:
  - rss:
      comments_path: "#__comments"

Material for MkDocs 将自动向您的网站添加 necessary metadata，使 RSS 源可以被浏览器和源阅读器发现。

此扩展的其他配置选项未被 Material for MkDocs 官方支持，因此可能会产生意想不到的结果。请自行承担风险使用它们。

仅博客¶

您可能需要构建一个没有任何文档的纯博客。在这种情况下，您可以创建如下的文件夹结构：

.
├─ docs/
│  ├─ posts/ # (1)!
│  ├─ .authors.yml
│  └─ index.md
└─ mkdocs.yml

1. 请注意，posts 目录位于 docs 的根目录中，没有中间的 blog 目录。

并将以下行添加到 mkdocs.yml 中：

plugins:
  - blog:
      blog_dir: . # (1)!

1. 有关 blog_dir 设置的更多信息，请参阅 plugin documentation。

使用此配置，博客文章的 URL 将是 /<post_slug> 而不是 /blog/<post_slug>。

使用¶

撰写您的第一篇文章¶

在成功设置 built-in blog plugin 后，是时候撰写您的第一篇文章了。该插件不假定任何特定的目录结构，因此您可以完全自由地组织您的文章，只要它们都位于 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: 2024-01-31 # (2)!
categories:
  - Hello
  - World
---

# Hello world!
...

1. 如果您将文章标记为 draft，则在索引页面上文章日期旁边会出现红色标记。当网站构建时，草稿不会包含在输出中。[此行为可以更改]，例如，在构建部署预览时渲染草稿。

2. 如果您希望提供多个日期，可以使用以下语法，允许您定义上次更新博客文章的日期 + 您可以添加到模板的其他自定义日期：

   ---
   date:
     created: 2022-01-31
     updated: 2022-02-02
   ---
   
   # Hello world!
   

   请注意，创建日期 必须 在 date.created 下设置，因为每篇博客文章必须设置创建日期。

当您启动 live preview server 时，您应该会看到您的第一篇文章！您还会发现，archive 和 category 索引已自动为您生成。

添加摘录¶

博客索引以及 archive 和 category 索引可以列出每篇文章的全部内容或文章的摘录。可以通过在文章的前几段后添加 <!-- 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 -->
...

当 built-in blog plugin 生成所有索引时，分隔符之前的内容会被自动提取，使用户在决定深入阅读之前可以开始阅读文章。

添加作者¶

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

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

.authors.yml 文件将每个作者与一个标识符（在此示例中为 squidfunk）关联，然后可以在文章中使用。可以配置不同的属性。有关所有可能属性的列表，请查阅 authors_file 文档。

现在，您可以通过在 Markdown 文件的前置属性中引用他们的标识符，将一个或多个作者分配给一篇文章。在每篇文章的左侧边栏以及索引页面的文章摘录中，都会渲染一个小型个人资料：

---
date: 2024-01-31
authors:
  - squidfunk
    ...
---

# Hello world!
...

添加作者个人资料¶

9.7.0

如果您希望为每位作者添加一个专门的页面，可以通过将 authors_profiles 配置选项设置为 true 来启用作者个人资料。只需将以下行添加到 mkdocs.yml 中：

plugins:
  - blog:
      authors_profiles: true

如果您将其与 custom index pages 结合使用，可以为每位作者创建一个专门的页面，包含简短描述、社交媒体链接等——基本上您可以在 Markdown 中编写的任何内容。文章列表将附加在页面内容之后。

添加类别¶

类别是将您的文章按主题分组的绝佳方式，以便在专门的索引页面上展示。这样，感兴趣于特定主题的用户可以浏览您在该主题上的所有文章。确保启用 categories 并将其添加到前置属性 categories 中：

---
date: 2024-01-31
categories:
  - Hello
  - World
---

# Hello world!
...

如果您想避免在输入类别时出现拼写错误，可以在 mkdocs.yml 中将所需类别定义为 categories_allowed 配置选项的一部分。 如果未在列表中找到类别， built-in blog plugin 将停止构建。

添加标签¶

除了 categories， built-in blog plugin 还与 built-in tags plugin 集成。如果您在前置属性 tags 中添加标签作为文章的一部分，则该文章将链接到 tags index：

---
date: 2024-01-31
tags:
  - Foo
  - Bar
---

# Hello world!
...

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

更改 slug¶

Slug 是用于 URL 的文章简短描述。它们会自动生成，但您可以为页面指定自定义 slug：

---
slug: hello-world
---

# Hello there world!
...

添加相关链接¶

9.6.0

相关链接提供了一个完美的方式，在您的文章中突出添加一个 进一步阅读 部分，该部分包含在左侧边栏中，引导用户到您文档的其他目的地。使用前置属性 links 为文章添加相关链接：

---
date: 2024-01-31
links:
  - plugins/search.md
  - insiders/how-to-sponsor.md
---

# Hello world!
...

您可以使用与 mkdocs.yml 中 nav 部分相同的语法，这意味着您可以为链接设置明确的标题、添加外部链接，甚至使用嵌套：

---
date: 2024-01-31
links:
  - plugins/search.md
  - insiders/how-to-sponsor.md
  - Nested section:
    - External link: https://example.com
    - setup/setting-up-site-search.md
---

# Hello world!
...

如果您仔细观察，您会发现您甚至可以使用锚链接到文档的特定部分，从而扩展 mkdocs.yml 中 nav 语法的可能性。built-in blog plugin 会解析锚并将锚的标题设置为相关链接的 subtitle。

请注意，所有链接必须相对于 docs_dir，与 nav 设置的情况相同。

从文章链接和到文章链接¶

虽然 post URLs 是动态计算的，但 built-in blog plugin 确保所有从文章到文章及其资产的链接都是正确的。如果您想链接到一篇文章，只需使用 Markdown 文件的路径作为链接引用（链接必须是相对的）：

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

从文章链接到页面，例如索引，遵循相同的方法：

[Blog](../index.md)

在构建网站时，posts 目录中的所有资产都会被复制到 blog/assets 文件夹中。当然，您也可以引用 posts 目录外的资产。built-in blog plugin 确保所有链接都是正确的。

固定文章¶

9.7.0

如果您希望将一篇文章固定在索引页面的顶部，以及它所包含的归档和类别索引中，可以使用前置属性 pin：

---
date: 2024-01-31
pin: true
---

# Hello world!
...

如果多篇文章被固定，则按创建日期排序，最新的固定文章将首先显示，随后是其他固定文章，按降序排列。

设置阅读时间¶

当 enabled 时，计算每篇文章的预期阅读时间，并作为文章和文章摘录的一部分呈现。如今，许多博客显示阅读时间，这就是 built-in blog plugin 提供此功能的原因。

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

---
date: 2024-01-31
readtime: 15
---

# Hello world!
...

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

设置默认值¶

9.6.0 meta – built-in

如果您有很多文章，为每篇文章定义上述所有内容可能会显得冗余。幸运的是，built-in meta plugin 允许按文件夹设置默认前置属性。您可以按类别或作者对文章进行分组，并添加一个 .meta.yml 文件以设置公共属性：

.
├─ docs/
│  └─ blog/
│     ├─ posts/
│     ├─ .meta.yml # (1)!
│     └─ index.md
└─ mkdocs.yml

1. 如前所述，您还可以将 .meta.yml 文件放置在 posts 目录的嵌套文件夹中。该文件可以定义在文章中有效的所有前置属性，例如：

   authors:
     - squidfunk
   categories:
     - Hello
     - World
   

请注意顺序很重要——built-in meta plugin 必须在 mkdocs.yml 中的博客插件之前定义，以便所有设置的默认值被 built-in blog plugin 正确拾取：

plugins:
  - meta
  - blog

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

添加页面¶

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

nav:
  - Blog:
    - blog/index.md
    - blog/authors.md
      ...

自定义¶

自定义索引页面¶

9.6.0

如果您想向自动生成的 archive 和 category 索引添加自定义内容，例如在文章列表之前添加类别描述，您可以手动在内置博客插件会创建的相同位置创建类别页面：

.
├─ docs/
│  └─ blog/
│     ├─ category/
│     │  └─ hello.md # (1)!
│     ├─ posts/
│     └─ index.md
└─ mkdocs.yml

1. 最简单的方法是首先 add the category 到博客文章，然后获取内置博客插件生成的 URL，并在 blog_dir 文件夹中的相应位置创建文件。

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

   • blog_dir
   • categories_url_format
   • categories_slugify

您现在可以向新创建的文件添加任意内容，或为此页面设置特定的前置属性，例如更改 page description：

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

# Hello
...

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

覆盖模板¶

[内置博客插件] 基于与 Material for MkDocs 相同的基础构建，这意味着您可以像往常一样使用 theme extension 覆盖用于博客的所有模板。

[内置博客插件] 添加了以下模板：

• blog.html – 博客、归档和类别索引的模板
• blog-post.html – 博客文章的模板