如何在mkdocs-material文档主题下设置多版本文档系统？

引言

前一段时间，参与了PaddleOCR开源项目的文档站点搭建工作，基于mkdocs工具，采用mkdocs-material主题，基于Github Pages来搭建整个文档站点。目前该站点已经搭建完毕， 支持多语言、文档搜索等诸多功能。

最近得知，PaddleOCR文档站点需要支持多版本文档功能。这个需求是可以实现的，因为当时调研各个文档工具时，mkdocs-material是支持部署多版本的文档需求的。

经过查看mkdocs-material使用文档以及查看网上其他小伙伴教程，总算将该部分实现了。在查找相关资料过程中，我发现没有一个较为完整清晰的文章来具体说明如何部署使用多版本文档站点的。因此，就有了本篇文章。

最终效果

• 文档站点默认为main分支下对应的文档内容
• 如果release代码时，会自动根据tag名称为当前文档生成tag对应的文档站点版本。类似如下(来源link)：

部署步骤

Step1: 配置mkdocs.yml文件

具体源码可参见PaddleOCR中mkdocs.yml中写法 → link

extra:
  version:
    provider: mike

Step2: 编写对应的workflow配置文件

该部分分为了2个workflow，一个是日常更新main分支，自动发布到对应文档版本下；另外一个是release tag时，自动发版到对应tag的文档站点。

build_publish_develop_docs.yml

name: Build/Publish Develop Docs
on:
  push:
    branches:
      - master
      - main
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 mike mkdocs-material jieba mkdocs-git-revision-date-localized-plugin mkdocs-git-committers-plugin-2 mkdocs-static-i18n
      - run: |
          git fetch origin gh-pages --depth=1
          mike deploy --push --update-aliases main latest
          mike set-default --push latest

• 注意上述配置文件中的pip install mike。整个多版本的文档站点功能支持得益于mike这个库。这个是必不可少的。
• git fetch origin gh-pages --depth=1这一步是为了先同步原有gh-pages分支代码。如果不存在gh--pages分支，需要先注释掉这行代码，等自动创建该分支后，再取消该行注释即可。
• mike deploy --push --update-aliases main latest： mike命令包含了原有的mkdocs的命令，因此这里可以只写mike deploy即可

build_publish_release_docs.yml

name: Build/Publish Release Docs
on:
  push:
    tags:
      - v*

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 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 mike mkdocs-material jieba mkdocs-git-revision-date-localized-plugin mkdocs-git-committers-plugin-2 mkdocs-static-i18n
      - run: |
          git fetch origin gh-pages --depth=1
          mike deploy --push "${{ github.ref_name }}" latest
          mike set-default --push latest

• 该配置文件与上一个区别在于：更改了触发条件。改为了打tag时，tag名称是以v开头时自动触发。这一点体现在代码：

  push:
    tags:
      - v*
  

• 发布对应的tag号的文档站点功能，体现在倒数第二行中mike deploy --push "${{ github.ref_name }}" latest下。其中${{ github.ref_name }}会获得tag名称

Step3: 提交到仓库，自动生成文档站点即可

具体相关源码，请参考PaddleOCR项目，有不明白的问题可以在评论区指出。