安装指南¶
本指南将帮助您安装 MkDocs 和 Material for MkDocs 主题。
前置要求¶
在开始之前，请确保您的系统已安装：
- Python 3.8 或更高版本
- pip（Python 包管理器）
安装步骤¶
1. 创建虚拟环境（推荐）¶
使用虚拟环境可以隔离项目依赖：
# 创建虚拟环境
python3 -m venv venv
# 激活虚拟环境
# Linux/macOS:
source venv/bin/activate
# Windows:
venv\Scripts\activate
2. 安装 Material for MkDocs¶
使用 pip 安装 Material for MkDocs（会自动安装 MkDocs）：
3. 验证安装¶
检查 MkDocs 是否正确安装：
您应该看到类似以下的输出：
使用 Docker（可选）¶
如果您更喜欢使用 Docker，可以使用官方 Docker 镜像：
# 拉取镜像
docker pull squidfunk/mkdocs-material
# 运行服务器
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
Docker 注意事项
Docker 容器仅用于本地预览，不适合生产部署。
依赖包说明¶
Material for MkDocs 会自动安装以下依赖：
| 包名 | 用途 |
|---|---|
| mkdocs | 核心静态站点生成器 |
| markdown | Markdown 解析器 |
| pygments | 代码语法高亮 |
| pymdown-extensions | Markdown 扩展 |
下一步¶
安装完成后，您可以：
故障排除¶
权限错误¶
如果遇到权限错误，请使用虚拟环境或添加 --user 标志：
版本冲突¶
如果遇到依赖版本冲突，尝试升级 pip：
网络问题¶
如果下载速度慢，可以使用国内镜像源：