5.4 KiB
5.4 KiB
MkDocs 使用说明
📝 编辑方式说明
❌ 不支持在线编辑
MkDocs 是一个静态文档生成工具，前端网站只能查看，不能在线编辑。
✅ 正确的使用方式
需要编辑 Markdown 文件并放入对应目录，MkDocs 会自动生成网站。
🔄 工作流程
编辑 Markdown 文件 → 保存文件 → MkDocs 自动检测变化 → 重新生成网站 → 浏览器自动刷新
📖 详细使用步骤
方式一：在服务器上直接编辑（推荐用于快速修改）
-
SSH 连接到服务器
ssh renjianbo@101.43.95.130 -
编辑文档文件
# 使用 vim 编辑 vim /home/renjianbo/devops/mkdocs/docs/index.md # 或使用 nano nano /home/renjianbo/devops/mkdocs/docs/index.md -
保存文件后，MkDocs 会自动重新加载（开发模式）
- 无需重启服务
- 浏览器刷新即可看到更新
方式二：本地开发后上传（推荐用于大量编辑）
-
在本地电脑上编辑
- 使用你喜欢的编辑器（VS Code、Typora、MarkText 等）
- 编辑
docs/目录下的 Markdown 文件
-
上传到服务器
# 使用 scp 上传 scp -r docs/ renjianbo@101.43.95.130:/home/renjianbo/devops/mkdocs/ # 或使用 rsync 同步 rsync -avz docs/ renjianbo@101.43.95.130:/home/renjianbo/devops/mkdocs/docs/ -
MkDocs 会自动检测变化并更新
方式三：使用 Git 管理（推荐用于团队协作）
-
在本地编辑并提交到 Git
cd /home/renjianbo/devops/mkdocs git add . git commit -m "更新文档" git push -
在服务器上拉取更新
ssh renjianbo@101.43.95.130 cd /home/renjianbo/devops/mkdocs git pull -
MkDocs 会自动更新
📁 文件组织
目录结构
docs/
├── index.md # 首页
├── 开发指南/
│ ├── 快速开始.md
│ ├── 项目结构.md
│ └── 开发规范.md
├── DevOps平台/
│ ├── Gerrit使用指南.md
│ ├── Gitea使用指南.md
│ └── ...
├── 技术文档/
│ ├── 架构设计.md
│ └── ...
└── 学习笔记/
├── Java学习.md
└── ...
添加新文档
-
创建 Markdown 文件
# 例如：添加新的学习笔记 touch /home/renjianbo/devops/mkdocs/docs/学习笔记/新主题.md -
编辑文件内容
# 新主题 这是新主题的内容... -
在 mkdocs.yml 中添加导航
nav: - 学习笔记: - 学习笔记/Java学习.md - 学习笔记/前端学习.md - 学习笔记/新主题.md # 添加这一行 -
保存后自动生效
🛠️ 常用编辑命令
查看现有文档
ls -la /home/renjianbo/devops/mkdocs/docs/
编辑文档
# 使用 vim
vim /home/renjianbo/devops/mkdocs/docs/index.md
# 使用 nano（更简单）
nano /home/renjianbo/devops/mkdocs/docs/index.md
创建新文档
# 创建新文件
touch /home/renjianbo/devops/mkdocs/docs/新文档.md
# 或直接编辑（如果不存在会自动创建）
nano /home/renjianbo/devops/mkdocs/docs/新文档.md
查看 MkDocs 日志（确认更新）
docker logs -f mkdocs
💡 编辑技巧
1. 使用本地编辑器（推荐）
在本地使用专业的 Markdown 编辑器：
- VS Code + Markdown 插件
- Typora（所见即所得）
- MarkText（开源免费）
2. 实时预览
MkDocs 开发模式支持自动刷新：
- 编辑文件并保存
- 浏览器会自动刷新显示最新内容
- 无需手动重启服务
3. 文件同步
如果需要在多台电脑上编辑：
- 使用 Git 管理文档
- 或使用 rsync/scp 同步文件
🔍 验证更新
编辑文件后，可以通过以下方式验证：
-
查看容器日志
docker logs mkdocs | tail -20应该看到类似信息：
INFO - Documentation built in 1.32 seconds INFO - [时间] Serving on http://0.0.0.0:8000/ -
刷新浏览器
- 访问 http://101.43.95.130:8000
- 按 F5 或 Ctrl+R 刷新
- 应该看到最新内容
❓ 常见问题
Q: 为什么不能在前端网站直接编辑？
A: MkDocs 是静态文档生成工具，它读取 Markdown 文件并生成静态 HTML 网站。前端只是展示，不提供编辑功能。
Q: 如果我想在线编辑怎么办？
A: 可以考虑以下方案：
- 使用 Wiki 系统（如 Gitea 的 Wiki 功能）
- 使用在线 Markdown 编辑器（如 HackMD、StackEdit）
- 使用 Git 工作流（本地编辑 → Git 提交 → 服务器拉取）
Q: 编辑后多久能看到更新？
A: 在开发模式下，保存文件后几秒钟内就会自动更新，刷新浏览器即可看到。
Q: 需要重启服务吗？
A: 不需要！MkDocs 开发模式会自动检测文件变化并重新生成网站。
📚 相关资源
总结：MkDocs 需要编辑 Markdown 文件，不能在前端网站直接编辑。编辑文件后，MkDocs 会自动生成更新的网站。