跳转至

记录开始尝试使用 mkdocs-material 搭建 blog 页面的过程

约 790 个字 • 91 行代码

本来以为在 Writing your first post 里能直接发布出一篇blog，但是发现还需要先配置(Configuration)好

Quote

Material for MkDocs makes it very easy to build a blog, either as a sidecar to your documentation or standalone. Focus on your content while the engine does all the heavy lifting, automatically generating archive and category indexes, post slugs, configurable pagination and more.

手册28

配置文件

先基本地添加blog插件，

plugin:
  - blog

如果使用默认配置，文件结构应该为：

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

并且必须将 blog 路径下的 index.md 添加到目录的配置中：

nav:
  - Blog:
    - blog/index.md

index.md 内官方给出的模板：

# Blog

当然想添加其他东西也可以自己添加

在 blog-dir 中说到，如果想将网页制作成一个独立博客(standalone blog)，可以将 blog-dir 设置成 . ：

plugins:
  - blog:
      blog_dir: .

那么如果其他的路径使用默认的设置的话，文件结构应该变成

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

那么之前的目录的设置应该改成

nav:
  - Blog:
    - index.md

之后我为了图省事，能使用默认的就使用默认的设置(推荐设置和默认设置一样的选项)，只添加推荐的配置和默认不一样的：

blog_toc 、 post_date_format 、 pagination_format 、 pagination_keep_content 、 draft_if_future_date

最后最终我的配置为：

plugins:
  - blog:
      blog_dir: .
      blog_toc: true
      post_date_format: full
      archive_toc: true
      categories_toc: true
      pagination_format: "$link_first $link_previous ~2~ $link_next $link_last"
      pagination_keep_content: true
      draft_if_future_date: true

Quote

Note that this setting is also used as the default value for archive_toc and categories_toc, unless those settings are explicitly defined.

发布第一篇blog

我先直接copy了 Writing your first post ，发布第一篇blog，

在之前的posts文件夹中新建博客的文档 test.md :

---
draft: true 
date: 2022-01-31 
categories:
  - Hello
  - World
---

# Hello world!
...

然后慢慢添加设置

设置摘要

Adding an excerpt

可以在主页只显示blog中 <!-- more --> 之上的内容，而隐藏之后的内容:

---
draft: false
date: 2023-09-11
authors:
  - ronald_luo
categories:
  - Configure & Debug
---

# 一次在github上询问作者的经历

>   2023-09-11

[Why does mkdocs-material display unsupported Chinese when running the mkdocs gh-deploy -- force command · squidfunk/mkdocs-material · Discussion #5992 (github.com)](https://github.com/squidfunk/mkdocs-material/discussions/5992)

<!-- more -->

## **stage 1**

作者让创建一个*最小复制件*然后上传，

...

except_1

except_2

设置作者

Adding authors

要在之前设置的blog的对应的路径下创建一个 .author.yml 文件：

authors:
  ronald_luo:
    name: Ronald Luo
    description: I'm A Student
    avatar: https://github.com/RonaldLN/MyPamphlet-Blog/blob/main/assets/avatar.jpg?raw=true

并且 name description avatar 三个选项均为必须

avatar 必须填入的图片的URL链接，不能填本地的路径

在单篇blog中加入作者( authors 选项)：

---
...
authors:
  - ronald_luo
  ...
...
---

# 记录开始尝试使用 mkdocs-material 搭建 blog 页面的过程

...

Adding categories

设置分类比较简单 易懂

Adding tags

添加tags在我的尝试过程中只能在搜索结果中显示tag，文章顶部并不能显示tag，感觉实用性不是很高，所以就没有添加这个东西

Setting the reading time

阅读时间在blog插件里内置有这个功能，不用设置也能显示阅读时间，但是如果认为不准的话，可以自己对单篇blog设置阅读时间而覆盖掉自动计算的

剩余的我认为有用的两个功能都需要赞助的版本才能使用

  • (在blog的左侧元数据部分)添加相关的链接 Adding related links
  • 设置默认的数据，包括作者什么的 Setting defaults](https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#setting-defaults)

插曲

测试时编写blog文档：

---
...
---

# Hello World

# Hello World

...

发现单篇blog中并没有显示目录(table of contents)，不像官方文档中的blog那样

于是在官方github上询问

How can I make the table of content appear for each post in my blog? · squidfunk/mkdocs-material · Discussion #5998 (github.com)

作者回复，只有只设置了一个一级标题，才能显示目录

经过测试和修改之后成功显示了目录

最后更新: 2023-10-28
创建日期: 2023-09-14

评论