前言

我在开发qqmusic-cli时需要为项目制作一个Wiki, 在参考这个项目编写API时觉得这个它的文档编写的很漂亮, 于是打算使用同款文档框架进行编写, 但是我由于初次接触这个框架, 加之网上关于使用mkdocs给项目编写文档的教程几乎没有, 结果我折腾了一晚上部署了一个框架上去.

1. 关于mkdocs安装

参考官网的安装步骤, 使用docker或者pip安装即可, 我原本希望全局使用mkdocs, 于是半小时速通了docker之后又修复了一堆bug, mkdocs镜像确实拉取下来了, 但是运行之后创建的文档全是root权限, 根本没法不用sudo编辑. 最后还是老老实实建了虚拟环境使用pip安装.

2. 在项目中初始化文档并部署

在项目中初始化文档就是直接按着官网的步骤在项目根目录下执行初始化指令(于我来说就是mkdocs new .), 此举会创建一个mkdocs.yml, 和一个docs目录(事先看看你的项目目录里面有没有一个docs或doc目录以免冲突), 按着官网步骤改写mkdocs.yml, 这就算基本完成了文档框架的初始化

mkdocs示例

接下来的部署步骤, 官网说的并不详细(仅仅之说需要使用github actions进行部署), 网上我也仅仅找到这一篇教程, 两者甚至有部分冲突, 因为在github设置中, 从github actions部署和从特定的branch部署根本就是相冲突的选项.

github设置中关于部署的部分冲突

下面的步骤就是将这两者混合起来(虽然很奇怪, 但是他真能部署上去).

2.1 设置github workflows

github workflows可以理解成一种项目push上去之后自动执行的脚本. 按照官网的步骤(其中按照github actions那个章节)先建立这个.github/workflows/ci.yml文件, 再进行修改

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
name: ci 
on:
  push:
    branches:
      - main
      - dev
    # - 这里填入任何你希望能够在push的同时进行部署操作的分支名称
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force

2.2 推送部署

先git add --all && git commit && git push, 推送到远程仓库之后, 等待工作流运行完毕, 在前文设置中设置成从特定分支部署网页.

此时你会看到多了gh-pages分支, 选择使用它的根目录部署, 即可在 https://<usr_name>.github.io/<proj_name>这一网址看到网页的框架

刚刚完成部署的框架