搭建过程

前言

本网站借助mkdocs和material for mkdocs搭建而成。

具体过程

安装工具

pip install mkdocs-material

生成模板 + 调整样式

可以自己搜索方法

如何展示公式?

用MathJax 和 KaTeX。参考这里。

发布网站

用github pages来发布。具体做法如下。

在github上新建一个仓库，名字需要符合格式: <自定义name>.github.io, 权限设置为public
把mkdocs new .创建得到的文件push到这个仓库上。
在mkdocs.yml同目录下执行：mkdocs gh-deploy --clean命令。（它会先用mkdocs build命令来生成html文件，然后将这些文件push到gh-pages分支）
配置：Settings -> Pages -> Build and deployment -> Branch -> gh-pages(root) -> save。
在Settings -> Pages -> Github Pages -> Your site is live at ...这里可以看到自己的网站链接，现在就可以访问辣。

自动更新

github Action实现，当有更新时，push到github上就自动更新网站。

在仓库根目录下新建文件：.github/workflows/ci.yml，在其中填写内容:

name: ci
on:
push:
    branches:
    - master
    - main
jobs:
deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-python@v2
        with:
        python-version: 3.x
    - run: pip install mkdocs-material
    - run: mkdocs gh-deploy --force

然后push到github上。这个文件会告诉github，当往主分支上push时去执行相关的更新操作。

然后要开启相关的权限。在github仓库页面，点击Settings -> Actions -> Workflow permissions -> Read and write permissions -> save。

加评论区

使用giscus来加评论区。

首先在docs同目录下创建文件夹overrides/partials，然后在这个文件夹下创建文件comments.html（一会儿再填充内容）
上github，保证（参考这里）：
自己的mkdocs的仓库是public的
在Settings中启用discussion
在github上安装giscus
然后在刚才的comments.html中填充内容，可以参考这里。
然后在mkdocs.yml中添加配置custom_dir: overrides：

theme:
  name: material
  custom_dir: overrides  # 添加评论系统用

然后想在哪个markdown界面添加评论区，就在这个markdown文档的最前面添加如下内容：

---
comments: true
---