本站总访问量次, 访客数人次

主页搭建

主页搭建借鉴了 pegasuswang。
主页技术栈为
1. mkdocs: quick start 参考 https://markdown-docs-zh.readthedocs.io/zh_CN/latest/#_8。
2. Python-Markdown-Math 编写公式
3. 自动部署 gh-pages: 参考 https://www.cnblogs.com/chinjinyu/p/17610438.html
For full documentation visit mkdocs.org.

mkdocs 构建命令

mkdocs new [dir-name] - Create a new project.
mkdocs serve - Start the live-reloading docs server.
mkdocs build - Build the documentation site.
mkdocs -h - Print help message and exit.
mkdocs gh-deploy # 部署到自己的 github pages, 如果是 readthedocs 会自动触发构建

项目布局

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

选择 material 主题

mkdocs 的 material 主题因为 极简风格 与 配色好看 十分吸引我。前者能让人专注于内容，后者则能够持续吸引人阅读。

配置

material 主题配置可以参考如下两个教程

Quick start 教程, 但是其中在 footer 里面添加邮箱等社交账号的配置方法已经过期了，新配置方法如下

# mkdocs.yml 相关配置
extra:
    social:
        -   icon: fontawesome/solid/paper-plane
            link: mailto:<shafish_cn@163.com>
            name: 邮箱地址

详细使用教程, 这哥们的博客主题就是 material, 这个教程也写的比较详细.
github markdow 语法支持 + 暗色模式
其他教程

material 主题中可以使用各种小图标(也叫 font)，比如将当前页翻到最后看到的纸飞机和邮箱图标。图标样式和名字可以从下面链接中找到。

插入图片

参考插入图片教程

自定义

虽然 material 主题默认配置已经很好了，但是免不了要做一些自定义修改，比如给页面添加一个统计访问量的功能。网页都是通过 markdown 写的，那怎么修改呢？

我这里先简单介绍下修改思路，只针对 mkdocs 的 material 主题，不一定适用其他主题。material 利用 flask 框架(报错栈中看到了flask关键字)写好网页模板，让后将 markdown 中的内容填到模板当中，然后再利用这个模板生成最终的 html 网页。因此，修改的思路就是修改预定义的 flask 网页模版。详细可以参考 material 网页自定义教程，主要分为如下几步：

添加自定义配置

theme:
  custom_dir: overrides ## 添加这个配置

在 mkdocs.yml 文件的同级目录下，新建overrides 目录
在 overrides 目录下创建需要覆盖的模板文件，并保证文件在 overrides中的相对位置和 material 网页自定义教程中一致。
修改模板文件，注意区别覆盖原来的模板还是在原来基础上新增内容。

下面以新增网站访问量为例介绍。

新增网站访问量功能

如前一小节所述
如前一小节所述
在 overrides 目录下新建 main.html 文件，这个是所有网页都会用到的主模板文件，按照 material 网页自定义教程要求，它存放的位置如下
```
.
├── README.md
├── docs
│   └── ...
├── mkdocs.yml
└── overrides
    └── main.html
```

main.html 中内容如下

{% extends "base.html" %} 这一句表示继承原模板，含义是除了新增、修改的内容，其他内容和原模板一样。
{% block announce %} 表示接下来修改的是网页中 announce 部分的内容
{{ super() }} 表示原模板中的 announce 部分的内容仍然保留
{% endblock %} 表示结束修改

其余的非注释部分内容是新加的

{% extends "base.html" %}

{% block announce %}
<script async src="https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>
<span id="busuanzi_container_site_pv">
    本站总访问量<span id="busuanzi_value_site_pv"></span>次, 访客数<span id="busuanzi_value_site_uv"></span>人次
</span>

  <!-- Add scripts that need to run before here -->
  {{ super() }}
  <!-- Add scripts that need to run afterwards here -->
{% endblock %}

新加内容中
1. 第一行的 <script async src="https:...</script>表示引用计算网站访问量的脚本，这里用的是不蒜子脚本，主要是简单、免费。
2. 第二行是计算网站访问量：busuanzi_value_site_pv 表示点击次数、busuanzi_value_site_uv表示访客人数

添加评论功能

我选 Github Pages 来自建网站写博客，因为

比起用知乎、CSDN等平台，自建博客的社交属性没有那么重，管理起来也更加方便
同时还自带版本管理、域名解析。

Github Pages 是静态网站，所以我一直狭隘地以为无法实现交互相关的功能，比如网站访问量统计、评论等。没想到也是有方法的。前面一节已经增加了网站访问量统计功能，这一节介绍下如何给静态网站（特指 Github Pages + mkdocs material）添加评论功能。

网上教程有推荐 Disque、livere 第三方博客评论系统的，注册后看了下价格，直接劝退。

经过多方搜索，找到两套免费实现的方案，都是借助 Github 实现

shafish的material教程推荐使用 Vssue
squidfunk 推荐的基于giscus搭建评论系统的教程，同时可以辅助参考 Giscus 申请教程

我更倾向于 2，因为是算是官方推荐的。

基于giscus搭建评论系统

安装 Giscus GitHub App 并将授予某个仓库用 Discussion 存储评论的权限，这个仓库可以不是存放 Github Pages 的 repo；权限授予可以参考 Giscus 申请教程

访问 Giscus 并生成如下代码片段 :

<script
  src="https://giscus.app/client.js"
  data-repo="<username>/<repository>"
  data-repo-id="..."
  data-category="..."
  data-category-id="..."
  data-mapping="pathname"
  data-reactions-enabled="1"
  data-emit-metadata="1"
  data-theme="light"
  data-lang="en"
  crossorigin="anonymous"
  async
>
</script>

借用 material 主题的自定义扩展功能，将评论模块插入到网站上。

在如下目录结构中新建 comments.html comments，为什么要是这个目录结构可以参考overriding partials

        .
        ├── README.md
        ├── docs
        │   └── ...
        │      
        ├── mkdocs.yml
        └── overrides
        ├── main.html
        └── partials
            └── comments.html

comments.html 里的内容如下

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

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

    /* Set palette on initial load */
    var palette = __md_get("__palette")
    if (palette && typeof palette.color === "object") {
      var theme = palette.color.scheme === "slate" ? "dark" : "light"
      giscus.setAttribute("data-theme", theme) // (1)!
    }

    /* Register event handlers after documented loaded */
    document.addEventListener("DOMContentLoaded", function() {
      var ref = document.querySelector("[data-md-component=palette]")
      ref.addEventListener("change", function() {
        var palette = __md_get("__palette")
        if (palette && typeof palette.color === "object") {
          var theme = palette.color.scheme === "slate" ? "dark" : "light"

          /* Instruct Giscus to change theme */
          var frame = document.querySelector(".giscus-frame")
          frame.contentWindow.postMessage(
            { giscus: { setConfig: { theme } } },
            "https://giscus.app"
          )
        }
      })
    })
  </script>
{% endif %}

在前面 comments.html 的高亮处下面粘贴在第 2 步中获得的 Giscus 授权代码
按网页开启评论功能：在需要开启评论的 markdown 文档前面添加如下注释
```
---
comments: true
---

# Page title
...
```

按网页所在的目录批量开启评论功能, 主要流程可以参考 built-in meta plugin, 但是有个配置过期了
```
plugins:
  - meta
```
应该改成
```
# 参考 https://pypi.org/project/mkdocs-meta-manager/
plugins:
    - meta-manager
    - search
```
由于我是使用 github action 自动触发编译+部署，所以需要配置安装对应插件的 python 安装包。 github action 配置安装 python 包参考下一小节。

安装 python 包依赖

在使用 material 主题时，希望用到一些高级功能，这个时候需要安装一些 mkdocs 插件，这些插件需要安装一些 python 包；而我又是通过 github action 自动编译+部署网站的，所以需要在 github action 上添加安装 python 包依赖的配置。我使用的是mkdocs-deploy-gh-pages配置 github action，通过它的 README 可以看到添加 python 包依赖的配置方法，mkdocs-deploy-gh-pages README 还描述了安装其他依赖的方法。(PS. 我开始没注意到这个README上有相关内容，还提了个issue问，现在感到非常 shameful) 具体做法是：

github action 的yml文件新增两行配置

name: Publish docs via GitHub Pages
on:
  push:
    branches:
      - main
jobs:
  build:
    name: Deploy docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout main
        uses: actions/checkout@v2
      - name: Deploy docs
        uses: mhausenblas/mkdocs-deploy-gh-pages@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          EXTRA_PACKAGES: build-base
          REQUIREMENTS: requirements.txt
          CONFIG_FILE: mkdocs.yml

在项目根目录下新建 requirements.txt 文件，文件中新增需要安装的 python 依赖
在 mkdocs.yml 新增所需插件，前文已提及，不赘述

一些有用的插件

material 主题支持 markdown 的 checkbox 语法，参考 mkdocs-material-checkbox

 markdown_extensions:
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true