如何将GitHub上的MkDocs文档自动同步至Azure DevOps Wiki？

1. 先搞定Azure DevOps的Git-backed Wiki #

Azure DevOps Wiki分两种，Git-backed类型支持用Git仓库管理，是自动化同步的首选：

• 进入项目Wiki页面，点击右上角「...」选择「Clone wiki」，复制仓库的HTTPS/SSH地址。
• 若是新建Wiki，直接选「Publish code as wiki」，创建或关联一个Git仓库作为Wiki的存储源。

2. 适配MkDocs内容到Azure Wiki规则 #

优先同步MkDocs源Markdown文件（推荐） #

MkDocs的源文件本身就是Markdown，只需调整两点：

• 目录结构：Azure Wiki的根目录对应仓库根，子目录对应页面层级，把MkDocs的docs目录内容直接同步到Wiki仓库根即可。
• 图片路径：将MkDocs里的图片路径（比如../assets/img/xxx.png）改成基于Wiki仓库根的相对路径，比如/assets/img/xxx.png，同时把图片文件夹同步到Wiki仓库对应位置。

若需同步生成后的静态内容（不推荐） #

如果必须用MkDocs生成的site目录下的HTML，可借助pandoc转成Markdown，但容易丢失格式和图片引用，谨慎使用。

3. 用自动化工具实现同步 #

方案1：GitHub Actions（适配GitHub源仓库） #

在GitHub仓库的.github/workflows下创建sync-to-azure-wiki.yml：

name: Sync MkDocs to Azure DevOps Wiki
on:
  push:
    branches: [ main ]  # 监听主分支提交

jobs:
  sync-wiki:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取GitHub仓库代码
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 克隆Azure DevOps Wiki仓库
        run: |
          git clone ${{ secrets.AZURE_WIKI_GIT_URL }} azure-wiki-repo
          cd azure-wiki-repo
          git config user.name "GitHub Actions Bot"
          git config user.email "actions@github.com"

      - name: 同步文档和图片
        run: |
          # 复制MkDocs源文档到Wiki仓库（根据实际目录调整）
          cp -r docs/* azure-wiki-repo/
          # 复制图片资源（示例路径，按需修改）
          cp -r assets/images/* azure-wiki-repo/assets/images/

      - name: 提交并推送
        run: |
          cd azure-wiki-repo
          git add .
          git commit -m "Sync from GitHub commit: ${{ github.sha }}" || echo "无内容更新"
          git push

• 配置：在GitHub仓库的「Settings > Secrets and variables > Actions」里添加AZURE_WIKI_GIT_URL，HTTPS格式需替换成带PAT的地址：https://<你的PAT>@dev.azure.com/<组织名>/<项目名>/_git/<Wiki仓库名>。

方案2：Azure Pipelines（适配Azure生态） #

• 新建Azure Pipeline，选择GitHub作为代码源。
• 编写Pipeline YAML，步骤和GitHub Actions类似：拉取GitHub代码、克隆Wiki仓库、同步内容、提交推送。
• 需配置Azure DevOps PAT，确保Pipeline拥有Wiki仓库的读写权限。

4. 关键注意事项 #

• 冲突避免：约定团队仅在GitHub上编辑文档，Azure Wiki作为只读镜像，防止手动编辑导致同步冲突。
• PAT权限：创建Azure DevOps PAT时，需勾选「Wiki > 读写」和「代码 > 读写」权限。
• 测试验证：先手动执行一次同步，检查文档格式、图片显示是否正常，再启用自动化。

内容的提问来源于stack exchange，提问作者Stalin Thomas