基本博客¶
¥Basic blogs¶
博客是与受众互动的绝佳方式。软件开发者可以使用博客发布新功能、演示其用法并提供背景信息。您可以通过评论最新技术来展示您的能力，或记录您自己的工作作为最佳实践。关于当前主题的帖子可以帮助您吸引访客访问您的主网站，并保持受众的参与度。当然，您可以撰写任何您感兴趣的主题的博客。
¥Blogs are a great way to engage with your audience. Software developers can use a blog to announce new features, demonstrate their usage and provide background information. You can demonstrate competence by commenting on the state of the art or document your own work as best practice. Posts on current topics can help draw in visitors for your main website and can keep your audience engaged. Of course, you can blog about any topics close to your heart.
博客插件可以轻松地与其他内容一起运行博客，但如果帖子是您唯一需要的内容，您也可以将其配置为运行独立博客。
¥The blog plugin makes running a blog alongside your other content easy but you can also configure it to run a stand-alone blog if posts are the only kind of content you need.
在简要概述博客的基本概念之后，本教程将指导您完成配置博客插件、设置博客、创建帖子和定义帖子元数据的过程。
¥After a brief overview of the basic concepts of a blog, this tutorial guides you through the process of configuring the blog plugin, setting up your blog, creating posts, and defining post metadata.
所需时间：通常 20 分钟
¥Time required: typically 20 minutes
关键概念¶
¥Key concepts¶
帖子、摘录：博客由多篇独立的帖子（通常称为文章）和一个按时间倒序显示帖子的索引页组成，最新帖子显示在顶部。索引页通常只显示一小段摘录和一个链接，用户可以点击该链接导航到完整的帖子。
¥Post, excerpt: a blog consists of a number of self-contained posts (often called articles) and an index page that shows the posts in reverse chronological order, with the most recent post at the top. The index page usually shows only a short excerpt and a link that the user can click to navigate to the full post.
元数据：索引页和帖子本身都列出了诸如您发布帖子的时间、您更新帖子的时间、作者是谁以及预计阅读时间是多少等信息。
¥Metadata: both the index page and the post itself list information such as when you published the post, when you updated it, who the author is, and what the expected reading time is.
Slug ：由于博客文章主要按时间排列，而非按层级结构排列，因此其 URL 并未体现这种结构。相反，每篇文章的 URL 都包含一个简短的描述，即slug ，它通常源自文章的第一个标题。
¥Slug: since the blog posts are primarily arranged by time and not into a hierarchy, their URLs do not reflect such a structure. Instead, each post's URL contains a shortened description, the slug, which is usually derived from the first heading in the post.
导航：主要导航结构是时间轴，您可以将其细分为多个类别。主索引页显示较新的帖子，而存档部分则允许访问按年份排列的较旧帖子。此外，帖子可以添加标签，标签索引页提供了基于内容的额外导航结构。
¥Navigation: the main navigation structure is the timeline, which you can subdivide into categories. The main index page shows the more recent posts while an archive section allows access to older ones, organized by year. In addition, posts can be tagged and tag index pages provide an additional navigation structure based on content.
您可以在Material for MkDocs 博客上看到所有这些元素。
¥You can see all these elements on the Material for MkDocs blog.
设置你的博客¶
¥Setting up your blog¶
博客插件是 MkDocs 的 Material 的一部分，但您需要在mkdocs.yml中对其进行配置。
¥The blog plugin is part of Material for MkDocs but you need to configure it in the mkdocs.yml.
建立博客
¥Set up a blog
如果您还没有这样做，请为您的博客创建一个项目，然后编辑mkdocs.yml文件以确保它具有以下内容：
¥If you have not done so already, create a project for your blog, then edit the mkdocs.yml file to make sure it has the following content:
site_name: Blog Tutorial
site_description: an example blog set up following the tutorial
site_url: http://www.example.com
theme:
name: material
plugins:
- search
- blog
如果不存在，博客插件将为您的博客文章创建一个目录结构，因此只需运行mkdocs serve即可：
¥The blog plugin will create a directory structure for your blog posts if it does not exist, so simply run mkdocs serve to get:
现在，在docs/blog/posts中创建你的第一篇博客文章。你可以使用任何你喜欢的命名约定和目录结构来创建文章，只要它们位于docs/blog/posts下即可。
¥Now create your first blog post in docs/blog/posts. You can use any naming convention and directory structure you like for your posts, as long as they are inside docs/blog/posts.
每篇文章都必须有一个页眉，它位于 Markdown 代码的顶部，位于三个短划线之间。页眉中至少需要包含一个date条目，但您也可以添加其他数据，如下所示。页眉之后是页面内容。请注意，一级标题非常重要，因为插件会使用它来生成slug 。此外，通过在页面中添加<!-- more --> ，您可以定义索引页显示的摘录结束位置。
¥Each post must have a page header, which appears at the top of the Markdown code between lines with three dashes. Within this header, you need to have at least a date entry but you can add other data, as you will see below. Following the header comes the page content. Note that it is important to have a level one heading as the plugin uses it to produce the slug. Also, by adding <!-- more --> to the page, you can define where the excerpt will end that the index page shows.
撰写你的第一篇文章
¥Write your first post
创建文件docs/blog/posts/myfirst.md内容如下：
¥Create a file docs/blog/posts/myfirst.md with the following contents:
---
date:
created: 2023-12-31
---
# Happy new years eve!
We hope you are all having fun and wish you all the best for the new year!
<!-- more -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
然后，运行mkdocs serve并将您的 Web 浏览器指向http://localhost:8000/blog 。
¥Then, run mkdocs serve and point your web browser at http://localhost:8000/blog.
博客插件会自动为博客创建导航元素。首页仅显示摘录。点击“继续阅读”链接，即可访问完整的博文。请注意，它有一个从一级标题生成的 URL。
¥The blog plugin automatically creates navigation elements for the blog. The index page shows only the extract. When you select the "Continue reading" link, you will get to the full blog post. Note how it has a URL generated from the first-level heading.
导航
¥Navigation
我们还有一个关于导航的教程，向您展示如何更改自动创建的导航，并将博客集成到您现有的导航结构中。它展示了如何创建二级导航、创建作者页面以及控制分页。
¥We also have a tutorial on navigation that shows you how to change the automatically created navigation and integrate the blog into your existing navigation structure. It shows how to create secondary navigation, produce author pages, and control pagination.
发布元数据¶
¥Post metadata¶
除了日期之外，您还可以提供其他元数据并给出插件指令，例如将帖子视为草稿或将其固定。
¥In addition to the date, you can provide other metadata and give the plugin instructions, such as to treat a post as a draft or to pin it.
草稿¶
¥Drafts¶
您可能希望生成博客文章草稿并在本地处理，但将其排除在发布的版本之外。只需在页面标题中添加一个字段，即可指示文章仍为草稿。
¥You may want to produce a draft of a blog post and work with it locally but exclude it from the build that you publish. Simply add a field to the page header to indicate that a post is still in draft form.
创建草稿
¥Create a draft
在docs/blogs/posts/draft.md中创建第二篇博客文章，内容如下：
¥Create a second blog post in docs/blogs/posts/draft.md with the following contents:
---
date:
created: 2024-01-01
draft: true
---
# Happy new year!
Happy 2024 to everyone. Wishing you all the best!
<!-- more -->
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
现在，请注意草稿如何显示在索引页上，但带有一个标签，表明它是草稿。当您运行mkdocs build时，草稿不会出现在输出中：
¥Now, note how the draft appears on the index page but with a label that indicates that it is a draft. When you run mkdocs build, the draft will not appear in the output:
$ mkdocs build
$ ls site/blog
site/blog
├── 2023
│ └── 12
│ └── 31
│ └── happy-new-years-eve
│ └── index.html
...
2024 年的第一篇博文尚未发布，因为它仍处于草稿阶段。发布时，请记住移除标题中的draft设置。
¥The first blog post for 2024 is not there yet because it is still in draft stage. Remember to remove the draft setting in the header when it is time to publish it.
如果您使用的是Insiders 版本，您还可以创建一个文件夹来保存草稿，并使用Meta 插件将draft标题设置添加到该文件夹中的所有帖子。这样做的好处是，您可以更轻松地查看哪些帖子仍处于草稿状态。我们稍后会介绍 Meta 插件。
¥If you are using the Insiders Edition, you can also create a folder to keep your drafts in and use the Meta plugin to add the draft header setting to all the posts in that folder. This has the advantage that it is easier to see which posts are still in draft form. We will cover the Meta plugin later on.
编辑¶
¥Edits¶
有时，博主需要更新帖子。这可能是因为您犯了错误，或者某些更改需要在帖子中反映出来。为了表明您已编辑帖子，您可以在页眉中添加updated日期。
¥Sometimes, bloggers need to update a post. This might happen when you make a mistake or when something changes that you need to reflect in the post. To indicate you have edited a post, you can include an updated date in the page header.
编辑帖子
¥Editing a post
对您的第一篇博客文章进行更改，然后在标题中添加编辑日期：
¥Make a change to your first blog post, then add an edit date to the header:
博客文章本身的元数据部分将包含编辑日期，但索引页默认省略此详细信息。
¥The Metadata section of the blog post itself will contain the edit date, though the index page omits this detail by default.
阅读时间¶
¥Reading time¶
为了让读者大致了解阅读一篇文章可能需要多长时间，系统会自动计算阅读时间。如果您想覆盖此设置，可以在页眉中指定您估计读者阅读这篇文章所需的分钟数。
¥To give the reader some idea of how long it might take them to read a post, a read time is automatically calculated. If you want to override this, you can do so in the page header by specifying the number of minutes you estimate your readers will take the read the post.
覆盖阅读时间
¥Overriding the reading time
为您的第一篇博客文章添加阅读时间覆盖：
¥Add a reading time override to your first blog post:
固定¶
¥Pinning¶
有时，博客作者希望将某篇文章“置顶”，以便无论其他文章发布后如何，它都会始终显示在首页顶部。如果您使用的是Insiders 版本，则可以通过在页眉中添加pin属性来实现此目的：
¥Sometimes, blog authors want to 'pin' a specific post so that it will always appear at the top of the index page, no matter what else gets published. If you are using the Insiders Edition, you can achieve this by adding the pin attribute in the page header:
置顶帖子
将pin属性添加到您的第一篇博客文章：
¥Add the pin attribute to your first blog post:
观察一下，即使该帖子的发布日期早于其他帖子，它也会显示在索引页的顶部。一个小图钉图标表示该帖子已被置顶。
¥Observe how this makes the post appear on top of the index page even though its publication date is prior to other posts. A small pin icon shows that the post has been pinned.
相关链接¶
¥Related links¶
当你的博客属于一个更广泛的网站（例如技术文档）时，你会希望在博客文章中提供指向其他内容的链接。一种方法是创建一个相关链接部分。如果你在页面标题中提供链接目标，博客插件可以为你创建一个：
¥When your blog is part of a wider site such as technical documentation, you will want to provide links from blog posts into your other content. One way you can do this is to have a related links section. The blog plugin can create one for you if you provide link targets in your page header:
添加相关链接部分
将以下内容添加到博客文章中：
¥Add the following to a blog post:
相关链接出现在元数据部分下方。
¥The related links appear underneath the Metadata section.
这里的好处是您无需提供页面标题。插件将使用与 MkDocs 用于主导航相同的逻辑来推断链接文本。实际上，其语法与mkdocs.yml中nav部分的语法相同，因此您可以根据需要覆盖标题，甚至可以定义子部分：
¥The nice thing here is that you do not need to provide a page title. The plugin will deduce the link text by applying the same logic that MkDocs uses for the main navigation. In fact, the syntax is the same as that of the nav section in the mkdocs.yml, so you can override the title if you want and even define subsections:
覆盖页面标题
¥Override the page titles
更改链接部分以覆盖页面标题：
¥Change the link section to override the page titles:
该插件会在屏幕宽度足够的情况下，将相关链接显示在左侧边栏；在屏幕宽度较窄的情况下，则显示在文章底部。请更改浏览器窗口大小以查看实际效果。
¥The plugin renders related links in the left sidebar on screens that are wide enough and at the bottom of the post on narrow screens. Change the size of your browser window to see this in action.
元插件¶
¥Meta plugin¶
Meta 插件有助于简化同一子目录中一组文件共用的元数据的管理。您无需在多个文件的页眉中重复相同的元数据，只需在目录中添加一个.meta.yml文件，Meta 插件就会将其内容合并到所有包含页面的页眉中。页眉中的设置优先，因此您可以随时通过将设置添加到文章页眉来覆盖这些设置。
¥The Meta plugin helps simplify the management of metadata that is common to a group of files in the same subdirectory. Instead of having to repeat the same metadata in the page headers of a number of files, you can add a .meta.yml file in the directory and the Meta plugin will merge its contents into the headers of all the pages contained. Settings from the page header take precedence, so you can always override settings by adding them to a post's header.
例如，您可能希望将草稿放在一个目录中进行管理，这样不仅可以将它们标记为草稿，而且更容易找到。（否则，您需要检查页眉或从输出追溯到文件才能确定哪些帖子是草稿。）
¥For example, you may want to manage drafts by keeping them in a directory together so that they are not only flagged as drafts but also easier to find. (Otherwise, you would need to inspect the page headers or trace back from the output to the files to figure out which posts are drafts.)
使用 Meta 插件的草稿
首先需要在mkdocs.yaml中激活该插件：
¥You first need to activate the plugin in your mkdocs.yaml:
现在创建草稿文件夹：
¥Now create the folder for the drafts:
现在，在此文件夹中，创建一个包含以下内容的文件.meta.yml ：
¥Now, within this folder, crate a file .meta.yml that contains:
添加另一篇博客文章并将其存储在docs/blog/posts/drafts中。在本地查看时，您会看到标明其为草稿的标签，但在为发布而构建的版本中，该标签不会显示。要将文章从草稿状态移至已发布状态，只需将其移出drafts/即可。
¥Add another blog post and store it in docs/blog/posts/drafts. When you look at it locally, you will see the label that identifies it as a draft, while in the version built for publication it does not appear. To move a post from draft status to published, simply move it outside drafts/.
下一步是什么？¶
¥What's next?¶
现在，您应该已经拥有一个可以正常运行的博客了。但是，随着内容的积累，您可能需要确保人们能够找到他们感兴趣的文章，因此您可能需要添加带有标签和类别的二级导航。您可能有多个作者，并且希望将文章归属到他们，并为他们生成作者页面。我们有一个关于导航、分页和作者的教程，涵盖了这些主题。
¥You should now have a working blog. However, as it accumulates content, you may want to make sure that people can find posts they are interested in, so you may want to add secondary navigation with tags and categories. You may have more than one author and want to attribute posts to them as well as generate author pages for them. We have a tutorial on navigation, pagination, and authors that covers these topics.
您可能希望通过允许人们订阅 RSS 源或设置评论系统来提高博客的互动性。参与度和传播度教程将指导您完成这些设置。
¥You may want to increase engagement with your blog by allowing people to subscribe to an RSS feed or by setting up a comment system. The engagement and dissemination tutorial walks you through setting these up.