滿喜歡用 Material for MkDocs 來產生文件網站，嚴格來說，這是一個建構在 MkDocs 之上的一個樣式套件，只是又加入了滿多設計樣式，相對於原始 MkDocs 來說在文件閱讀排版上更清晰。

以前常用 Sphinx 寫 rst 格式的純文字內容，後來 Markdown 成為主流，延伸出許多靜態網頁套件或是對應 Markdown 轉換其他文件格式的應用。我記得我是在使用 FastAPI、Pydantic 的技術文件注意到為什麼有一套很美的文件產生樣板，使用後就決定採用在當時做的專案，建構文件資訊給予其他貢獻者參與、閱讀。

以往所建立 Material for MkDocs 的文件專案，大部分都會將建立好的靜態網頁上傳到 AWS S3 存放，直接透過 AWS S3 的網站設定或是透過 nginx 路徑轉址合併到原有的網站中（如：/docs）。反而發現從來沒嘗試過直接用 Github Pages 來建立 Material for MkDocs 文件專案。

在 Github Actions 中有三種方式可以實現 Github Pages 的發佈，可以參考這份 yaml 檔案的描述。這裡用的套件管理是 uv。

MkDocs 有整合 Github Pages 的發佈，可以透過 mkdocs gh-deploy 來佈署，直接一行指令就可以完成。

- name: Build MkDocs
  run: |
      uv run mkdocs gh-deploy -b gh-pages -d ./docs

直接將產生出來的靜態檔案 ./docs 內的檔案上傳到 gh-pages 分支的頂層位置。

第二種方式是每次都從 main 建立一個新的分支 gh-pages 然後產生靜態文件後，強迫上傳覆蓋遠端原有的 gh-pages，這樣的方式是只會看到最新的文件提交紀錄。

- name: Build MkDocs
  run: |
      uv run mkdocs build -d ./docs
      git checkout -b gh-pages main
      git add -f ./docs
      git commit -m 'Deploy MkDocs to GitHub Pages'
      git push -f origin gh-pages

第三種方式是用 worktree 的方式將 gh-pages 建立在 ./docs，然後把靜態文件產生到 ./docs 中完成提交與推送。

- name: Build Mkdocs
  run: |
      git worktree add ./docs gh-pages
      rm -rf ./docs/*
      uv run mkdocs build -v -d ./docs
      cd ./docs
      if [ -n "$(git status --porcelain)" ]; then
        git add .
        git commit -a -m 'Deploy on ${{ github.ref_name }} ${{ github.sha }}'
        git push origin HEAD
      else
        echo "No changes to commit."
      fi

歷史紀錄

如果有使用 mkdocs-git-revision-date-localized-plugin 套件，應該會發現每次產生出來的文件建立日期與修改日期都會是一樣的，那是因為 Github Actions 在使用 actions/checkout 的時候不會擷取過往的 git 歷史提交，需要指定參數來提示擷取完整的 git 紀錄。

- uses: actions/checkout@v5
  with:
      fetch-depth: 0

以上，透過三種方式來建立 Material for MkDocs 靜態文件，看起來多行的指令是可以保留一些彈性操作的可能，例如在最後更換 og 預覽圖，當使用免費版本，都只能呈現預設的樣式。

Material for MkDocs 是一個很好快速建立靜態文件或是針對專案類型的說明網站，建立在 Github Pages 上也不用擔心主機安全性或流量問題，覺得這是一個值得投入瞭解與應用的靜態文件套件！