部署 MkDocs 站点
Python Markdown 文档 SSG，Material 主题部署到 GitHub Pages 或任何静态主机。
平台入门
为什么
MkDocs 是 Python 编写的快速简单文档 SSG — Markdown 输入，HTML 输出。Material 主题加搜索、暗色模式和 60+ 语言支持，配置极少。
平台即服务采用率 2024 年增长 24%，团队从虚拟机管理转向 git push 部署。the cloud infrastructure market reached $330B in 2024, growing 22% year-over-year (Synergy Research)，PaaS 层捕获了大多数新工作负载。
何时使用
Python 项目文档和偏好 Markdown 而非 MDX 的团队用 MkDocs。React 交互文档避免 — 用 Docusaurus。
如何做
1. 构建 — mkdocs build 输出 site/
2. 部署 — mkdocs gh-deploy 推送到 gh-pages 分支
3. 配置 — mkdocs.yml 配主题、导航、插件
4. Material — pip install mkdocs-material 流行主题
5. 服务 — mkdocs serve 本地开发实时重载
示例
# mkdocs.yml
site_name: My Docs
theme:
name: material
features:
- navigation.tabs
- search.suggest
plugins:
- search
# 部署到 GitHub Pages
mkdocs gh-deploy
# 部署到任何主机
mkdocs build && npx wrangler pages deploy site
常见问题
- ⚠Material 主题未应用 — 构建环境忘记 pip install mkdocs-material
- ⚠子路径搜索断 — mkdocs.yml 中 site_url 未正确设置
- ⚠环境间配置漂移 — 使用基础设施即代码（Terraform/Pulumi）保持 dev/staging/prod 一致
最佳实践
- ✓用 mkdocs-material — 最佳主题，活跃维护、搜索和 i18n
- ✓requirements.txt 固定 mkdocs 和 material 版本 — 可复现构建
- ✓设置健康检查和优雅关闭 — 处理 SIGTERM 以在退出前排空进行中的请求