構建文件網站

文件原始檔位於 docs/，導航和站點設定位於 mkdocs.yml。生成的 HTML 位於 site/，該目錄不應提交到 Git。

本地預覽

在專案虛擬環境中安裝文件依賴：

python -m pip install --index-url https://pypi.org/simple/ -r requirements-docs.txt
python -m mkdocs serve

訪問 http://127.0.0.1:8000/。修改 Markdown 後，開發伺服器會自動重新構建頁面。

構建靜態 HTML

python -m mkdocs build --strict

--strict 會將導航或內部連結警告視為構建失敗。將 site/ 的內容上傳到任意靜態網站服務即可釋出。

GitHub Pages

倉庫提供 .github/workflows/docs.yml：

1. 開啟倉庫的 Settings → Pages。
2. 將 Build and deployment → Source 設定為 GitHub Actions。
3. 推送到 master 或 main，或手動執行 Docs workflow。
4. 在 workflow 的 deployment URL 或倉庫 Pages 設定中開啟網站。

從模板建立新專案後，更新 mkdocs.yml 中的 site_name、site_description、repo_name、repo_url 和 edit_uri。

文件結構

mkdocs.yml                  MkDocs 配置和导航
requirements-docs.txt      文档构建依赖
pyproject.toml             所有直接依赖和 profile 的唯一配置源
docs/                       中文文档
docs/en/                    英文文档
docs/images/                两种语言共用的图片
.github/workflows/docs.yml  GitHub Pages 构建与部署
site/                       生成的静态 HTML（已忽略）

新增頁面後，將頁面加入 mkdocs.yml 的 nav，並執行嚴格構建檢查。