MkDocs + Material 主题使用笔记

最近基于 MkDocs + Material 主题给学校做了一个电子白板维护手册，发现这个软件和主题可定制性相当丰富，而且坑也比较多，故在此整理成文。

环境配置

MkDocs 是一个使用 Python 编写的软件，要想使用它就必须安装 Python 环境。由于我需要在 Netlify 上做 CI/CD，而这个服务商的 Python 环境版本最高可选 3.7，所以我在我的电脑上也安装了 Python 3.7.9。

为了方便部署时配置环境，除了将项目文件夹存在单独的文件夹里之外，还需要创建一个 Python 虚拟环境，以后的操作都在这个虚拟环境里运行。这不仅有助于生产环境的依赖配置，还可以防止本机的开发环境被污染。

在我使用的终端环境（Powershell）中，创建并激活虚拟环境应这样操作：

python -m venv docs
cd docs
./Scripts/Activate.ps1

接下来安装 MkDocs 和 Material 主题，并初始化文档项目：

pip install mkdocs mkdocs-material
mkdocs new .

然后在项目文件夹内 mkdocs.yml 的 theme 字段中，将 name 改为 material. 可以运行一下 mkdocs serve 命令测试效果。

配置 Markdown extensions

MkDocs 使用的 Markdown 语法是最清真的版本，缺乏很多 GitHub Flavored Markdown（下简称 GFM）中的方便语法，比如删除线在 GFM 中只要使用 ~~ 标记即可，而原生 Markdown 并没有这个语法。

但是，MkDocs 支持自行加载 Markdown extensions 来添加语法，只要编辑 mkdocs.yml 的 markdown_extensions 字段 即可。我添加了以下扩展：

markdown_extensions:
  - admonition #MkDocs 警告框
  - footnotes #脚注
  - meta #自定义文章元数据
  - pymdownx.caret #下划线
  - pymdownx.mark #文本高亮
  - pymdownx.tilde #删除线
  - toc: # 大纲
      permalink: true
      slugify: !!python/name:pymdownx.slugs.uslugify

配置暗色模式

作为一个被没有暗色模式困扰已久的人，自己做的网页项目怎能没有暗色模式？

Material 主题内建对暗色模式的支持，但那个文档写的有点不明不白，我反反复复试了半天才知道应该这么配置：

在 mkdocs.yml 的 theme 字段中，添加一个与 name 同级的 palette 字段，里面这么写：

palette: 
    - scheme: default
      toggle:
        icon: material/weather-night
        name: 暗色模式
    - scheme: slate
      toggle:
        icon: material/weather-sunny
        name: 亮色模式

这样，访客就可以通过点击页面上方的按钮来切换亮色/暗色模式了。

当然，让访客自己切换可不是好主意，因为当访客在黑暗的环境下看见按钮时，他/她的眼睛就已经被亮瞎了。MkDocs 还支持通过媒体查询的方式，自动切换亮色/暗色模式。要实现这个特性，需要这么改动配置：

palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/weather-night
        name: 暗色模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/weather-sunny
        name: 亮色模式

默认的强调色 indigo 并不适合在暗色模式下阅读，所以还可以在暗色模式的 palette 处加一行 primary: teal （或者你喜欢的，适合在暗色背景下阅读的其他颜色）来更改暗色模式下的强调色。最终的配置如下：

palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/weather-night
        name: 暗色模式
    - media: "(prefers-color-scheme: dark)"
      primary: teal
      scheme: slate
      toggle:
        icon: material/weather-sunny
        name: 亮色模式