MkDocs+Material 静态博客

纯静态博客实现方案，可以基于Github Pages类似服务免费无服务器搭建。

MkDocs

MkDocs 是一个快速、简单且彻头彻尾的华丽静态站点用于构建项目文档的生成器。文档源文件是用 Markdown 编写的，并使用单个 YAML 进行配置配置文件。它的设计易于使用，可以进行扩展第三方主题、插件和 Markdown 扩展。

Material for MkDocs

Material for MkDocs 是一个MkDocs主题，可以进行高度定制和美化。

使用Python安装Material

1	pip install mkdocs-material mkdocs-redirects mkdocs-minify-plugin

pip包管理器会自动安装相关依赖，安装完毕后使用mkdocs命令无报错即可

使用Git安装Material

1 2	git clone https://github.com/squidfunk/mkdocs-material.git pip install -e mkdocs-material

使用Docker安装Material

使用docker可以避免繁琐的环境配置以及各种各样的报错

此次以Linux为例：

1	docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .

--rm：容器运行完成后会自动删除。

创建默认站点

1	mkdocs new .

.
├─ docs/
│  └─ index.md # 文档文件，即你编写的文档
└─ mkdocs.yml # 配置文件，采用yaml语法

再次构建站点

在完成编辑后，添加新文章到mkdocs.yml配置文件，使用以下命令完成构建站点

1	mkdocs build --clean

如果使用docker则使用以下命令构建
--rm：容器运行完成后会自动删除。

1	docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build

发布站点

将生成的site目录内所有文件，完整的复制到web服务器站点根目录即可

本站使用 Gitee Pages 进行托管，此次给出Github Action自动构建发布工作流配置

配置 GitHub Action 实现自动构建发布

1	nano .github/workflows/ci.yml

写入以下内容：

name: Publish site
on: # 在什么时候触发工作流
  push: # 在从本地main分支push到GitHub仓库时
    branches:
      - main
  pull_request: # 在main分支合并别人提的pr时
    branches:
      - main
jobs: # 工作流的具体内容
  deploy:
    runs-on: ubuntu-latest # 创建一个新的云端虚拟机 使用最新Ubuntu系统
    steps:
      - uses: actions/checkout@v4 # 先checkout到main分支
      - uses: actions/setup-python@v4 # 再安装Python3和相关环境
        with:
          python-version: 3.10 # 定义使用的Python版本
      - run: pip install mkdocs-material # 使用pip包管理工具安装mkdocs-material
      - run: mkdocs gh-deploy --force # 使用mkdocs-material部署gh-pages分支

      - name: delete old workflows # 自动删除旧的工作流
        uses: Mattraks/delete-workflow-runs@v2
        with:
          retain_days: 1
          keep_minimum_runs: 3

如果你使用 Github Action，可以跳过构建的过程，因为当你 Push 到GitHub时会自动帮你构建一个新的分支 gh-pages

本地部署则需要将 site 目录作为网站根目录

使用 Github Pages 托管

新建GitHub仓库

仓库名称：{username}/{username}.github.io

将以上文件推送至仓库，并配置相关的Github Pages 即可在相应网址查看

实时编写预览

mkdocs包含一个实时预览服务，因此你可以边写边预览，当你保存时他会自动渲染，使用以下命令启动服务：

1	mkdocs serve

它会启动一个web服务，输出如下：

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - index.md
INFO    -  Documentation built in 0.52 seconds
INFO    -  [11:51:10] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [11:51:10] Serving on http://127.0.0.1:8000/re_0/
WARNING -  [11:51:10] "GET /re_0/mkdocs/css/no-footer.css HTTP/1.1" code 404
WARNING -  [11:51:10] "GET /re_0/mkdocs/css/unordered-list-symbols.css HTTP/1.1" code 404
WARNING -  [11:51:10] "GET /re_0/mkdocs/javascripts/mathjax.js HTTP/1.1" code 404
INFO    -  [11:51:12] Browser connected:
           http://127.0.0.1:8000/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

重要更新提示

Material 9.x 版本需要 Python ≥3.8
默认分支从 master 改为 main
新增安全策略需在GitHub Pages设置中手动启用

推荐安装质量监控插件：

1	pip install mkdocs-broken-links-plugin mkdocs-monorepo-plugin