About the site\#

如你所见，这是一个使用MkDocs搭建的Blog网站，并且使用了Material for MkDocs作为主题，绝大部分的配置都可以通过查看上面的链接解决，但是我在这里想要强调的是一些需要注意和特别有用的项，这些是在你面对内容庞大详实的文档时，容易变得不耐烦而忽略的点

配置文件\#

关于我的个人配置，查看: My mkdocs.yml

配置`palette`主题颜色\#

如果需要使用自己喜欢的颜色，在这里添加：

- primary: custom # color of nav bar

然后引入extra.css并添加颜色配置

需要注意的是，这可能会导致亮暗模式的切换失灵，目前我还没有找到合适的解决方法

指定文章分类\#

可以在plugins中的blog中指定文章类别，防止拼写错误和随意添加，如果出了错误，在进行构建的时候引擎会报错提示

categories_allowed:
  - Math            # 对于偏向解决单个数学问题和疑惑的，主要为分散化内容
  - CS              # 跟计算机科学相关性大的内容
  - Tutorial        # 主要为系统性教程，内容偏长
  - Language        # 学习语言时遇到的一些问题
  - Log             # 在各种折腾中对问题和过程的记录，主要为技术性实践
  - Technology      # 非常容易和前面的内容搞混淆，这里主要记录某些具体的技术

元数据 metadata\#

所谓的元数据，可以理解为给文章分配的属性，这是不会轻易改变的数据，也有些地方会叫做 Front-matter ，正常情况下在编辑文章的时候把元数据按下面的格式写在Markdown文件的最开头就可以，不允许开头空行且必须顶格，如果编辑器有空格的行为的话，就会导致数据失效，不起作用。在本站配置中，只需要有下面的信息就可以了：

---
title:
date: 2024-01-01
categories: 
  - 在设置的预选项中选择
slug: 设置post的标题
tags: 
  - 
  - 
---

需要注意categories虽然一般情况下只有一个，但是也要求必须向上面一样以数组的形式书写

如果每次创建一个 blog 文章都要填写这样的元数据，未免有些麻烦了，因此我会使用一个 Python 脚本来完成元数据的初始化，然后我只需要将内容按照格式填写在这个文件里即可

摘录\#

如果使用blog插件，那么引擎就会自动抓取相应目录下的文章，并且一股脑地全部放到一个page中，这个时候就会导致信息非常多，且浏览起来不方便，引擎提供了Adding an excerpt功能，允许我们在Markdown中通过加入分隔符来显示摘要，引擎会只显示标题和分隔符上面的内容，自动视其为摘要，而后面的部分则被省略

注释\#

注释的方法查看 Reference/Annotations

如果需要在如引用等结构中使用注释，可以使用

<div class="annotate" markdown>
> 这里是内容...
</div>

上面这种写法就不用加{ .annotate }了

Warning

需要注意注释由1.这样的类似于有序列表的形式引导，因此一个注释只能占用一行，如果想要多行注释，目前暂时没有好的办法

图标和 emojis\#

material 主题准备了很多可用的图标和 emoji

更多查看: Material: Icons, Emojis, 提供搜索复制功能, 并且说明了如何用css给纯色图标加颜色和动效

自定义添加图标并设置快捷引用方式查看: Material: Changing the logo and icons

这里我在mkdocs.yml文件同级目录下创建了overrides并添加.icons文件夹, 在这个文件夹里添加我们想要自定义添加图标, 以文件夹的形式分类存储, 我自己创建的图标, 我将其保存在了my文件夹下, 并且使用下面示例的图标来表示文章的状态:

测试:

:my-green-point: 用于表示完成度较高或已经完结的文章, 后续不太可能进行大的修改, 即使进行修改也只是一些小修小补, 更新与别的文章的连接

:my-orangepi-point: 用于表示目前正在做的, 并且已经对于全局有所认识的文章, 很快就能补全内容

:my-red-point: 用于表示完全全新的领域, 不知道进行下去会是什么结果的内容

更多水彩图:

いらすとや

当然, 现在的 unicode 字符也已经包含了非常多好用的 emoji, 你可以快速地查询想要使用的字符的 unicode 编号或是它的 HTML Entity, 以 🟢Green Circle为例:

在 Markdown 中我们就可以直接使用它的 HTML 表示法: 🟢🟢一样得到了结果

告示 Admonitions\#

Admonitions 像一个小牌子, 用来提示读者一些不同属性的信息, 如警告, 错误, 更多信息, 小 tips 等, 因为它有着各种不同种类的提示, 并且支持自定义提示, 所以我倾向于叫它告示而不是警示

详细使用方法查看: Material: admonitions

代码块配置\#

查看 code-blocks