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: 亮色模式

本博客所有文章除特别声明外,均采用 CC BY-SA 4.0 协议 ,重用本文章时请遵守该协议。