構建文件網站

English · 文件中心

本倉庫使用 Material for MkDocs 將 docs/ 下的 Markdown 生成靜態 HTML 網站。站點導航、主題和搜尋配置位於倉庫根目錄的 mkdocs.yml。

安裝文件依賴

在倉庫根目錄執行：

$py = if (Test-Path .\.venv\Scripts\python.exe) { ".\.venv\Scripts\python.exe" } else { "python" }
& $py -m pip install -r requirements-docs.txt

本地預覽

& $py -m mkdocs serve

開啟終端顯示的本地地址。修改 Markdown 後，瀏覽器會自動重新整理。

生成靜態 HTML

& $py -m mkdocs build --strict

生成結果位於 site/ 目錄。該目錄可以部署到 GitHub Pages、Cloudflare Pages、靜態 Web 伺服器或物件儲存。

--strict 會把無效連結、缺失頁面和配置警告當作構建失敗，建議在提交文件前始終使用。

新增頁面

1. 在 docs/ 或 docs/en/ 下建立 Markdown 檔案。
2. 使用相對於當前檔案的連結引用其他頁面和圖片。
3. 在 mkdocs.yml 的 nav 中加入頁面。
4. 同時維護中文和英文入口的語言切換連結。
5. 執行嚴格構建，確認站點無警告。

圖片等靜態資源必須放在 docs/ 內。不要提交生成的 site/ 目錄。