mkdocs/部署说明.md

# 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
![图片描述](images/example.png)
```

### 内部链接

```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. **保持更新**: 定期更新文档内容

---

**开始编写你的文档吧！** 📝