基础博客¶
博客是与受众互动的绝佳方式。软件开发人员可以利用博客来宣布新功能，演示其用法并提供背景信息。通过评论最新技术动态或记录自己的最佳实践，您可以展示自己的能力。关于当前主题的帖子可以帮助吸引访问者到您的主网站，并保持受众的参与。当然，您可以撰写任何您热衷的话题。
blog plugin 使得在其他内容旁边运行博客变得简单，但您也可以将其配置为运行独立博客，如果帖子是您所需的唯一内容类型。
在对博客基本概念进行简要概述后，本教程将引导您完成配置 blog plugin、设置博客、创建帖子和定义帖子元数据的过程。
所需时间： 通常为 20 分钟
关键概念¶
帖子、摘录：博客由多个自包含的 帖子（通常称为文章）和一个索引页面组成，索引页面按时间倒序显示帖子，最新的帖子位于顶部。索引页面通常只显示一个简短的 摘录 和一个用户可以点击以导航到完整帖子的链接。
元数据：索引页面和帖子本身都列出信息，例如您何时发布了帖子，何时更新了它，作者是谁，以及预计的阅读时间。
Slug：由于博客帖子主要按时间排列，而不是按层次结构排列，因此它们的 URL 不反映这种结构。相反，每个帖子的 URL 包含一个简短的描述，即 slug，通常源自帖子的第一个标题。
导航：主要导航结构是时间线，您可以将其细分为 类别。主索引页面显示较新的帖子，而 归档 部分允许访问较旧的帖子，按年份组织。此外，帖子可以被 标记，而 标签索引页面 提供基于内容的额外导航结构。
您可以在 Material for MkDocs blog 上看到所有这些元素。
设置您的博客¶
博客插件是 Material for MkDocs 的一部分，但您需要在 mkdocs.yml 中进行配置。
设置博客
如果您还没有这样做，请为您的博客创建一个项目， 然后编辑 mkdocs.yml 文件以确保其包含以下内容：
site_name: 博客教程
site_description: 按照教程设置的示例博客
site_url: http://www.example.com
theme:
name: material
plugins:
- search
- blog
如果博客插件不存在，它将为您的博客帖子创建一个目录结构，因此只需运行 mkdocs serve 即可获得：
现在在 docs/blog/posts 中创建您的第一篇博客帖子。您可以使用任何命名约定和目录结构，只要它们位于 docs/blog/posts 中。
每个帖子 必须 有一个页面标题，它出现在 Markdown 代码的顶部，位于三条横线之间。在此标题中，您需要至少有一个 date 条目，但您可以添加其他数据，正如您下面将看到的。标题之后是页面内容。请注意，拥有一个一级标题是很重要的，因为插件使用它来生成 slug。此外，通过在页面中添加 <!-- more -->，您可以定义索引页面显示的摘录结束位置。
撰写您的第一篇帖子
创建一个文件 docs/blog/posts/myfirst.md，内容如下：
---
date:
created: 2023-12-31
---
# 新年快乐！
我们希望大家都玩得开心，并祝愿大家新年快乐！
<!-- more -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
然后，运行 mkdocs serve 并在您的网页浏览器中访问 http://localhost:8000/blog。
博客插件会自动为博客创建导航元素。索引页面只显示摘录。当您选择“继续阅读”链接时，您将进入完整的博客帖子。请注意，它的 URL 是从一级标题生成的。
导航
我们还有一个 导航教程，展示了如何更改 自动创建的导航并将博客集成到您现有的 导航结构中。它展示了如何创建二级导航、生成 作者页面和控制分页。
帖子元数据¶
除了日期，您还可以提供其他元数据并给插件指令，例如将帖子视为草稿或将其置顶。
草稿¶
您可能希望生成一篇博客帖子的草稿并在本地进行处理，但将其排除在您发布的构建之外。只需在页面标题中添加一个字段以指示帖子仍处于草稿状态。
创建草稿
在 docs/blogs/posts/draft.md 中创建第二篇博客帖子，内容如下：
---
date:
created: 2024-01-01
draft: true
---
# 新年快乐！
祝大家2024年快乐，万事如意！
<!-- more -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
现在，注意草稿在索引页面上出现，但带有指示它是草稿的标签。当您运行 mkdocs build 时，草稿将 不会 出现在输出中：
$ mkdocs build
$ ls site/blog
site/blog
├── 2023
│ └── 12
│ └── 31
│ └── happy-new-years-eve
│ └── index.html
...
2024年的第一篇博客帖子尚未出现，因为它仍处于草稿阶段。记得在发布时从标题中移除 draft 设置。
您还可以创建一个文件夹来保存草稿，并使用 Meta plugin 将 draft 标头设置添加到该文件夹中的所有帖子。这有一个好处，就是更容易看到哪些帖子仍处于草稿状态。我们稍后将介绍 Meta plugin。
编辑¶
有时，博主需要更新帖子。这可能发生在您犯了错误或需要在帖子中反映某些变化时。要指示您已编辑帖子，可以在页面标题中包含一个 updated 日期。
博客帖子的元数据部分将包含编辑日期，尽管索引页面默认省略此细节。
阅读时间¶
为了给读者提供一个大致的阅读时间，系统会自动计算阅读时间。如果您想覆盖此设置，可以在页面标题中指定您估计读者阅读帖子所需的分钟数。
置顶¶
有时，博客作者希望“置顶”特定帖子，以便它始终出现在索引页面的顶部，无论其他帖子何时发布。您可以通过在页面标题中添加 pin 属性来实现这一点：
置顶帖子
在您的第一篇博客帖子中添加 pin 属性：
请注意，这使得该帖子即使在其发布日期早于其他帖子时也出现在索引页面的顶部。一个小的图钉图标显示该帖子已被置顶。
相关链接¶
当您的博客是更大网站的一部分，例如技术文档时，您可能希望在博客帖子中提供指向其他内容的链接。您可以通过创建一个相关链接部分来实现这一点。如果您在页面标题中提供链接目标，博客插件可以为您创建一个相关链接部分：
添加相关链接部分
在博客帖子中添加以下内容：
相关链接出现在元数据部分下方。
这里的好处是您无需提供页面标题。插件将通过应用 MkDocs 对主导航使用的相同逻辑来推导链接文本。实际上，语法与 mkdocs.yml 中的 nav 部分相同，因此如果您愿意，可以覆盖标题，甚至定义子部分：
覆盖页面标题
更改链接部分以覆盖页面标题：
插件在足够宽的屏幕上将相关链接渲染在左侧边栏，在窄屏幕上则渲染在帖子底部。调整浏览器窗口的大小以查看效果。
Meta plugin¶
Meta plugin 有助于简化同一子目录中一组文件的元数据管理。您无需在多个文件的页面标题中重复相同的元数据，只需在目录中添加一个 .meta.yml 文件，Meta plugin 将其内容合并到所有页面的标题中。页面标题中的设置优先，因此您始终可以通过将其添加到帖子的标题中来覆盖设置。
例如，您可能希望通过将草稿保存在一个目录中来管理草稿，这样它们不仅被标记为草稿，而且更容易找到。（否则，您需要检查页面标题或从输出追溯到文件，以确定哪些帖子是草稿。）
使用 Meta plugin 管理草稿
首先，您需要在 mkdocs.yaml 中激活插件：
现在创建草稿的文件夹：
现在，在此文件夹中创建一个文件 .meta.yml，内容为：
添加另一篇博客帖子并将其存储在 docs/blog/posts/drafts 中。当您在本地查看时，您将看到标识其为草稿的标签，而在构建用于发布的版本时，它不会出现。要将帖子从草稿状态移至已发布状态，只需将其移动到 drafts/ 之外即可。
接下来是什么？¶
您现在应该有一个可用的博客。然而，随着内容的积累，您可能希望确保人们能够找到他们感兴趣的帖子，因此您可能希望添加带有标签和类别的二级导航。您可能有多个作者，并希望将帖子归属给他们，并为他们生成作者页面。我们有一个 导航、分页和作者的教程，涵盖了这些主题。
您可能希望通过允许人们订阅 RSS 源或设置评论系统来增加与博客的互动。 互动和传播教程 将指导您完成这些设置。