218 lines
4.2 KiB
Markdown
218 lines
4.2 KiB
Markdown
# MkDocs 个人知识库部署说明
|
|
|
|
## 📋 简介
|
|
|
|
MkDocs 是一个基于 Markdown 的文档生成工具，使用 Material 主题提供美观的文档界面。
|
|
|
|
## 🚀 快速开始
|
|
|
|
### 1. 启动服务
|
|
|
|
```bash
|
|
cd /home/renjianbo/devops/mkdocs
|
|
docker-compose up -d
|
|
```
|
|
|
|
### 2. 访问地址
|
|
|
|
- **本地访问**: http://localhost:8000
|
|
- **服务器访问**: http://101.43.95.130:8000
|
|
|
|
### 3. 查看日志
|
|
|
|
```bash
|
|
docker-compose logs -f
|
|
```
|
|
|
|
## 📁 目录结构
|
|
|
|
```
|
|
mkdocs/
|
|
├── docker-compose.yml # Docker Compose 配置
|
|
├── mkdocs.yml # MkDocs 配置文件
|
|
├── docs/ # 文档源文件目录
|
|
│ ├── index.md # 首页
|
|
│ ├── 开发指南/ # 开发相关文档
|
|
│ ├── DevOps平台/ # DevOps 工具文档
|
|
│ ├── 技术文档/ # 技术文档
|
|
│ └── 学习笔记/ # 学习笔记
|
|
└── site/ # 构建后的静态站点（可选）
|
|
```
|
|
|
|
## ✏️ 编辑文档
|
|
|
|
### 添加新文档
|
|
|
|
1. 在 `docs/` 目录下创建 Markdown 文件
|
|
2. 在 `mkdocs.yml` 的 `nav` 部分添加导航项
|
|
3. 保存后，页面会自动刷新（开发模式）
|
|
|
|
### 编辑现有文档
|
|
|
|
直接编辑 `docs/` 目录下的 Markdown 文件，保存后自动刷新。
|
|
|
|
### 示例：添加新章节
|
|
|
|
1. 创建文件 `docs/新章节/内容.md`
|
|
2. 在 `mkdocs.yml` 中添加：
|
|
|
|
```yaml
|
|
nav:
|
|
- 新章节:
|
|
- 新章节/内容.md
|
|
```
|
|
|
|
## 🔧 常用命令
|
|
|
|
### 启动服务
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### 停止服务
|
|
|
|
```bash
|
|
docker-compose down
|
|
```
|
|
|
|
### 重启服务
|
|
|
|
```bash
|
|
docker-compose restart
|
|
```
|
|
|
|
### 查看日志
|
|
|
|
```bash
|
|
docker-compose logs -f
|
|
```
|
|
|
|
### 构建静态站点
|
|
|
|
```bash
|
|
docker-compose exec mkdocs mkdocs build
|
|
```
|
|
|
|
构建后的静态文件会生成在 `site/` 目录。
|
|
|
|
### 进入容器
|
|
|
|
```bash
|
|
docker exec -it mkdocs sh
|
|
```
|
|
|
|
## 📝 配置说明
|
|
|
|
### 修改站点信息
|
|
|
|
编辑 `mkdocs.yml` 文件：
|
|
|
|
```yaml
|
|
site_name: 个人知识库
|
|
site_description: 个人技术文档和知识管理平台
|
|
site_author: renjianbo
|
|
site_url: http://101.43.95.130:8000/
|
|
```
|
|
|
|
### 修改主题
|
|
|
|
在 `mkdocs.yml` 的 `theme` 部分修改主题配置。
|
|
|
|
### 添加插件
|
|
|
|
在 `mkdocs.yml` 的 `plugins` 部分添加插件。
|
|
|
|
## 🎨 功能特性
|
|
|
|
- ✅ **Material 主题**: 美观现代的界面
|
|
- ✅ **全文搜索**: 快速查找内容
|
|
- ✅ **响应式设计**: 支持各种设备
|
|
- ✅ **深色模式**: 支持主题切换
|
|
- ✅ **代码高亮**: 支持多种编程语言
|
|
- ✅ **数学公式**: 支持 LaTeX 公式
|
|
- ✅ **流程图**: 支持 Mermaid 流程图
|
|
|
|
## 📚 使用技巧
|
|
|
|
### 代码块
|
|
|
|
使用三个反引号包裹代码，并指定语言：
|
|
|
|
```markdown
|
|
```python
|
|
def hello():
|
|
print("Hello, World!")
|
|
```
|
|
|
|
```
|
|
### 表格
|
|
|
|
```markdown
|
|
| 列1 | 列2 | 列3 |
|
|
|-----|-----|-----|
|
|
| 值1 | 值2 | 值3 |
|
|
```
|
|
|
|
### 图片
|
|
|
|
将图片放在 `docs/images/` 目录，使用相对路径：
|
|
|
|
```markdown
|
|
|
|
```
|
|
|
|
### 内部链接
|
|
|
|
```markdown
|
|
[链接文本](../其他文档.md)
|
|
```
|
|
|
|
### 外部链接
|
|
|
|
```markdown
|
|
[链接文本](https://example.com)
|
|
```
|
|
|
|
## 🔍 故障排查
|
|
|
|
### 端口被占用
|
|
|
|
如果端口 8000 被占用，修改 `docker-compose.yml` 中的端口映射：
|
|
|
|
```yaml
|
|
ports:
|
|
- "8001:8000" # 改为其他端口
|
|
```
|
|
|
|
### 页面不更新
|
|
|
|
1. 检查文件是否保存
|
|
2. 查看容器日志：`docker-compose logs mkdocs`
|
|
3. 重启服务：`docker-compose restart`
|
|
|
|
### 权限问题
|
|
|
|
确保文件有正确的权限：
|
|
|
|
```bash
|
|
chown -R renjianbo:renjianbo /home/renjianbo/devops/mkdocs
|
|
```
|
|
|
|
## 📖 相关资源
|
|
|
|
- [MkDocs 官方文档](https://www.mkdocs.org/)
|
|
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
|
|
- [Markdown 语法指南](https://www.markdownguide.org/)
|
|
|
|
## 💡 最佳实践
|
|
|
|
1. **定期备份**: 定期备份 `docs/` 目录和 `mkdocs.yml`
|
|
2. **版本控制**: 使用 Git 管理文档
|
|
3. **文档组织**: 按主题分类组织文档
|
|
4. **保持更新**: 定期更新文档内容
|
|
|
|
---
|
|
|
|
**开始编写你的文档吧！** 📝
|