如何在GitLab Pages中通过mike实现mkdocs版本化自动部署

这套方案全程不需要本地执行任何mike相关操作，本地只需要修改文档内容、推送tag即可，所有版本管理、文档构建、发布动作全在GitLab远程侧执行。

前置配置 #

• 仓库根目录已经存在可正常运行的mkdocs.yml配置文件，mike相关的版本选择器、别名规则等配置直接写在该文件中即可
• 进入GitLab项目的「设置 > CI/CD > 变量」，确认开启CI_JOB_TOKEN的仓库写入权限（默认新版本GitLab已开启，若权限不足可手动添加具备仓库写权限的项目访问令牌作为变量）
• 进入GitLab项目的「设置 > Pages」，将Pages部署源设置为gh-pages分支的根目录（后续mike会自动维护该分支的内容，无需手动创建）

编写CI流水线配置 #

在仓库根目录新建.gitlab-ci.yml文件，可根据自身使用的mkdocs主题、插件调整依赖安装项：

variables:
  # 关闭浅克隆，拉取全量分支和tag，保证mike能识别所有历史版本
  GIT_DEPTH: 0

stages:
  - deploy

deploy_docs:
  stage: deploy
  image: python:3.11-slim
  rules:
    # 仅在推送tag时触发部署
    - if: $CI_COMMIT_TAG
  before_script:
    # 安装依赖，按需替换为你实际用到的mkdocs主题、插件
    - pip install --no-cache-dir mkdocs mike mkdocs-material
    # 配置git提交信息，供mike提交版本记录使用
    - git config --global user.name "GitLab CI Bot"
    - git config --global user.email "ci-bot@noreply.internal"
  script:
    # 提取tag中的版本号，若你的tag不带v前缀可直接使用$CI_COMMIT_TAG
    - export DOC_VERSION=${CI_COMMIT_TAG#v}
    # 执行mike部署：推送当前版本到gh-pages分支，同时更新latest别名指向最新版本
    # 不需要latest别名可去掉对应参数，需要新增其他别名直接在后面追加即可
    - mike deploy --push --update-aliases $DOC_VERSION latest
    # 设置站点默认打开最新版本
    - mike set-default --push latest

使用流程 #

日常开发完全不需要接触版本管理相关操作：

• 本地修改文档内容，正常提交、推送到对应开发分支、合并到主分支即可，不需要本地执行mkdocs构建、mike版本维护类命令
• 需要发布对应版本的文档时，本地直接打对应tag（比如git tag v1.0.0），将tag推送到远程仓库即可
• 推送tag后GitLab会自动触发流水线，执行完成后GitLab Pages站点会自动新增对应版本的文档，页面上的版本切换器会自动展示所有已发布的版本

可选调整 #

• 如果需要给大版本维护统一别名，比如给所有v1.x的版本绑定stable别名，直接在mike deploy命令后追加别名参数即可
• 如果需要下线旧版本，可新增一个手动触发的CI任务，在任务中执行mike delete --push 待删除版本号即可，全程不需要本地操作
• 如果需要自定义版本排序、版本选择器样式，直接修改mkdocs.yml中的mike配置项，提交后下次发版自动生效

内容的提问来源于stack exchange，提问作者Joy Jedidja Ndjama