MkDocs 美化与进阶 - 零式岚の地下室

说明
本文核心内容在笔者的笔记本网站原文中亦有记载，此页面为整理重制版。

有了前面的一系列工作，我们的 MkDocs 网站已经可以正常生成和部署了，请读者务必对整套流程熟悉之后再继续阅读本文。

本文中，笔者将通过几个例子，介绍一些 MkDocs 的高级用法。

配置评论系统#

有很多评论系统可以集成到 MkDocs 中，这里选用最常用的 Giscus 作为例子，请读者以官方文档为准。

首先要安装 Giscus GitHub App 并授权给你的仓库。

然后，去 Giscus 官网，跟着提示引导一步一步走下来，会获得一段代码，类似这样：

1
<script src="https://giscus.app/client.js"
2
        data-repo="Fanovian/notebook"
3
        data-repo-id="R_kgDOJ2i3-Q"
4
        data-category="Announcements"
5
        data-category-id="DIC_kwDOJ2i3-c4CXtT_"
6
        data-mapping="pathname"
7
        data-strict="0"
8
        data-reactions-enabled="1"
9
        data-emit-metadata="0"
10
        data-input-position="bottom"
11
        data-theme="preferred_color_scheme"
12
        data-lang="zh-CN"
13
        crossorigin="anonymous"
14
        async>
15
</script>

接着在网站根目录创建目录和文件编辑 overrides/comments.html 文件：

1
{% if page.meta.comments %}
2
  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
3
  <!-- Insert generated snippet here -->
4

5
  <!-- Synchronize Giscus theme with palette -->
6
  <script>
7
    var giscus = document.querySelector("script[src*=giscus]")
8

9
    // Set palette on initial load
10
    var palette = __md_get("__palette")
11
    if (palette && typeof palette.color === "object") {
12
      var theme = palette.color.scheme === "slate"
13
        ? "transparent_dark"
14
        : "light"
15

16
      // Instruct Giscus to set theme
17
      giscus.setAttribute("data-theme", theme)
18
    }
19

20
    // Register event handlers after documented loaded
21
    document.addEventListener("DOMContentLoaded", function() {
22
      var ref = document.querySelector("[data-md-component=palette]")
23
      ref.addEventListener("change", function() {
24
        var palette = __md_get("__palette")
25
        if (palette && typeof palette.color === "object") {
26
          var theme = palette.color.scheme === "slate"
27
            ? "transparent_dark"
28
            : "light"
29

30
          // Instruct Giscus to change theme
31
          var frame = document.querySelector(".giscus-frame")
32
          frame.contentWindow.postMessage(
33
            { giscus: { setConfig: { theme } } },
34
            "https://giscus.app"
35
          )
36
        }
37
      })
38
    })
39
  </script>
40
{% endif %}

第三行的  处粘贴上面的 Giscus 代码。

如果你对前端三件套比较了解，也可以对这个文件进行一些修改，比如添加一些样式。

配置好之后记得在 mkdocs.yml 文件中添加：

1
theme:
2
  custom_dir: overrides

来把这个文件引入到主题中。除此之外，许多其他自定义的 html 文件也可以放在这个文件夹中，这里直接在主题中一次引入了。

然后在你想要添加评论的页面的 Markdown 文件的头部添加：

1
---
2
comments: true
3
---

即可在这个页面中添加评论系统。

添加顶部公告#

在 overrides 文件夹中创建 main.html 文件：

1
{% extends "base.html" %}
2

3
{% block announce %}
4
  <!-- Add announcement here, including arbitrary HTML -->
5
{% endblock %}

中间填写 HTML 格式的公告内容。

然后在 mkdocs.yml 文件中添加：

1
theme:
2
  custom_dir: overrides
3
  features:
4
    - announce.dismiss

最后一行的作用是读者可以关闭公告直至公告内容更新，关掉功能则公告常驻。

自定义配色和字体#

这个属于 CSS 的内容了。在 docs 文件夹下创建 stylesheets 文件夹，然后在其中创建 extra.css 文件。

在 extra.css 文件中写入你的 CSS 代码，比如：

1
:root {
2
    --md-primary-fg-color:        #0287ac;
3
    --md-primary-fg-color--light: #0287ac;
4
    --md-primary-fg-color--dark:  #0287ac;
5
    --md-accent-fg-color:         #0287ac;
6

7
    /* --md-text-font: "LXGW WenKai Screen";
8
    --md-code-font: "Menlo", "LXGW WenKai Screen"; */
9
}
10

11
[data-md-color-scheme="default"] {
12
    --md-footer-bg-color--dark: #ffffffd5;
13
    --md-footer-fg-color--light: #000000c6;
14
    --md-footer-fg-color--lighter: #0000009d;
15
    --md-footer-fg-color--lightest: #000000;
16
}
17

18
[data-md-color-scheme="slate"] {
19
    --md-default-bg-color: #131313;
20
    /* --md-default-bg-color--light: #161616;
21
    --md-default-bg-color--lighter: #161616;
22
    --md-default-bg-color--lightest: #161616; */
23
    --md-default-fg-color: rgba(255, 253, 253, 0.868);
24
    --md-default-fg-color--light: rgba(255, 255, 255, 0.854);
25
    --md-default-fg-color--lighter: rgba(255, 255, 255, 0.393);
26
    --md-default-fg-color--lightest: rgba(255, 255, 255, 0.58);
27
    --md-primary-fg-color: #1f1e33;
28
    --md-typeset-a-color: #ffffff;
29
    --md-footer-fg-color: #fff;
30
    --md-footer-bg-color: var(--md-default-bg-color);
31
    --md-footer-bg-color--dark: var(--md-default-bg-color);
32
    --md-footer-fg-color--light: #ffffffc3;
33
    --md-footer-fg-color--lighter: #ffffffc4;
34
    --md-code-bg-color: #1c1c1c;
35
}
36

37
.md-header__title {
38
    font-weight: bold;
39
    font-family: "LXGW Wenkai Screen", sans-serif;
40
}

笔者这里对日间模式和夜间模式都单独设置了一些自己喜欢的颜色，这些颜色的参数很多，具体可以看 Material for MkDocs 作者给出的示例，里面包含了所有的颜色定义。

同时笔者也对字体进行了设置，这里设置了正文和代码的字体，这里的字体是笔者自己下载的字体，你可以根据自己的喜好更改，可以是网上的字体链接，也可以下载之后引入。

我的字体选择#

正文中，笔者使用非常出名的开源字体霞鹜文楷，这是一款非常适合中文阅读的字体，同时也支持英文和数字。在网站设置中，参考了文章在站点网页中使用霞鹜文楷（LXGW WenKai），将字体 CSS 链接引入，使用的是屏幕阅读优化的版本。

代码字体是 Maple Font，具体可以前往其官网查看，比较符合笔者的审美。

我的配色方案#

夹带点私货 (*´∀`)~♥

网站的日间模式主题色（#0287ac）来源于动画《Girls Band Cry》中登场角色河原木桃香的代表色（#85c9dc），经过针对可读性的优化而得。
网站的夜间模式主题色（#1f1e33）来源于曲师かめりあ的 Arcaea 独占曲目《#1f1e33》。

插件的引入#

笔者使用了两个额外的 MkDocs 插件。

一个是 TonyCrane 学长的字数统计插件。

TonyCrane

mkdocs-statistics-plugin

Waiting for api.github.com...

00K

Waiting...

另一个是 ignorantshr 和 timvink 开发的自动标题插件。

ignorantshr

mkdocs-add-number-plugin

Waiting for api.github.com...

00K

Waiting...

插件的具体使用方式直接看仓库中的 README 即可。

需要注意的是，在本地安装好插件就可以渲染出效果，但是在 GitHub Pages 上渲染出效果需要构建页面的工作流中让 GitHub Actions 安装这些插件，需要在 PublishMySite.yml 文件中添加：

1
jobs: # 工作流的具体内容
2
  deploy:
3
    runs-on: ubuntu-latest # 创建一个新的云端虚拟机 使用最新Ubuntu系统
4
    steps:
5
      - uses: actions/checkout@v2 # 先checkout到main分支
6
      - uses: actions/setup-python@v2 # 再安装Python3和相关环境
7
        with:
8
          python-version: 3.x
9
      - run: pip install mkdocs-material # 使用pip包管理工具安装mkdocs-material
10
      - run: pip install mkdocs-statistics-plugin # 安装mkdocs-statistics-plugin
11
      - run: pip install mkdocs-add-number-plugin # 安装mkdocs-add-number-plugin
12
      - run: mkdocs gh-deploy --force # 使用mkdocs-material部署gh-pages分支

即先安装好所有的插件，然后再部署网站。否则 Actions 会报错。

此外在网站的主页自定义样式中还用到了下列插件：

一言插件：hitokoto
网站访问量统计插件：不蒜子