环境搭建
本教程带你从零开始，把 EOCC 文档库跑在本地，为后续写作和预览做准备。
1. 安装 Python
MkDocs 基于 Python 运行：
- Windows / macOS：到 python.org 下载安装包，安装时勾选 Add Python to PATH
- Linux：
sudo apt install python3 python3-pip
安装后验证：
python3 --version
pip3 --version
2. 安装 MkDocs 与主题
pip3 install mkdocs mkdocs-material
如果系统提示 externally-managed-environment（PEP 668 保护），推荐用虚拟环境：
python3 -m venv ~/docs-venv
~/docs-venv/bin/pip install mkdocs mkdocs-material
# 之后把 mkdocs 替换为 ~/docs-venv/bin/mkdocs 即可
3. 克隆文档仓库
git clone https://github.com/eoccc/eoccc.github.io.git
cd eoccc.github.io
没有命令行经验？也可以先跳过克隆，用 GitHub 网页端编辑（见提交与上线流程）。
4. 启动本地预览
mkdocs serve
看到 Serving on http://127.0.0.1:8000/ 即成功，浏览器打开该地址。此后修改任何 docs/*.md 保存，页面自动刷新。
常见问题
| 现象 | 原因与解决 |
|---|---|
mkdocs: command not found |
Python Scripts 目录不在 PATH，或用了虚拟环境却没带全路径 |
pip install 报权限错误 |
加 --user 参数，或改用虚拟环境 |
| 端口 8000 被占用 | mkdocs serve -a 127.0.0.1:8888 换端口 |
| 预览正常但字体/图标缺失 | 检查是否安装了 mkdocs-material 而不是仅有 mkdocs |
环境就绪后，请继续阅读 Markdown 写作规范。