mkdocs/使用说明.md

# MkDocs 使用说明

## 📝 编辑方式说明

### ❌ 不支持在线编辑

**MkDocs 是一个静态文档生成工具，前端网站只能查看，不能在线编辑。**

### ✅ 正确的使用方式

**需要编辑 Markdown 文件并放入对应目录，MkDocs 会自动生成网站。**

## 🔄 工作流程

```
编辑 Markdown 文件 → 保存文件 → MkDocs 自动检测变化 → 重新生成网站 → 浏览器自动刷新
```

## 📖 详细使用步骤

### 方式一：在服务器上直接编辑（推荐用于快速修改）

1. **SSH 连接到服务器**
   
   ```bash
   ssh renjianbo@101.43.95.130
   ```

2. **编辑文档文件**
   
   ```bash
   # 使用 vim 编辑
   vim /home/renjianbo/devops/mkdocs/docs/index.md
   
   # 或使用 nano
   nano /home/renjianbo/devops/mkdocs/docs/index.md
   ```

3. **保存文件后，MkDocs 会自动重新加载**（开发模式）
   
   - 无需重启服务
   - 浏览器刷新即可看到更新

### 方式二：本地开发后上传（推荐用于大量编辑）

1. **在本地电脑上编辑**
   
   - 使用你喜欢的编辑器（VS Code、Typora、MarkText 等）
   - 编辑 `docs/` 目录下的 Markdown 文件

2. **上传到服务器**
   
   ```bash
   # 使用 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/
   ```

3. **MkDocs 会自动检测变化并更新**

### 方式三：使用 Git 管理（推荐用于团队协作）

1. **在本地编辑并提交到 Git**
   
   ```bash
   cd /home/renjianbo/devops/mkdocs
   git add .
   git commit -m "更新文档"
   git push
   ```

2. **在服务器上拉取更新**
   
   ```bash
   ssh renjianbo@101.43.95.130
   cd /home/renjianbo/devops/mkdocs
   git pull
   ```

3. **MkDocs 会自动更新**

## 📁 文件组织

### 目录结构

```
docs/
├── index.md                    # 首页
├── 开发指南/
│   ├── 快速开始.md
│   ├── 项目结构.md
│   └── 开发规范.md
├── DevOps平台/
│   ├── Gerrit使用指南.md
│   ├── Gitea使用指南.md
│   └── ...
├── 技术文档/
│   ├── 架构设计.md
│   └── ...
└── 学习笔记/
    ├── Java学习.md
    └── ...
```

### 添加新文档

1. **创建 Markdown 文件**
   
   ```bash
   # 例如：添加新的学习笔记
   touch /home/renjianbo/devops/mkdocs/docs/学习笔记/新主题.md
   ```

2. **编辑文件内容**
   
   ```markdown
   # 新主题
   
   这是新主题的内容...
   ```

3. **在 mkdocs.yml 中添加导航**
   
   ```yaml
   nav:
     - 学习笔记:
       - 学习笔记/Java学习.md
       - 学习笔记/前端学习.md
       - 学习笔记/新主题.md  # 添加这一行
   ```

4. **保存后自动生效**

## 🛠️ 常用编辑命令

### 查看现有文档

```bash
ls -la /home/renjianbo/devops/mkdocs/docs/
```

### 编辑文档

```bash
# 使用 vim
vim /home/renjianbo/devops/mkdocs/docs/index.md

# 使用 nano（更简单）
nano /home/renjianbo/devops/mkdocs/docs/index.md
```

### 创建新文档

```bash
# 创建新文件
touch /home/renjianbo/devops/mkdocs/docs/新文档.md

# 或直接编辑（如果不存在会自动创建）
nano /home/renjianbo/devops/mkdocs/docs/新文档.md
```

### 查看 MkDocs 日志（确认更新）

```bash
docker logs -f mkdocs
```

## 💡 编辑技巧

### 1. 使用本地编辑器（推荐）

在本地使用专业的 Markdown 编辑器：

- **VS Code** + Markdown 插件
- **Typora**（所见即所得）
- **MarkText**（开源免费）

### 2. 实时预览

MkDocs 开发模式支持自动刷新：

- 编辑文件并保存
- 浏览器会自动刷新显示最新内容
- 无需手动重启服务

### 3. 文件同步

如果需要在多台电脑上编辑：

- 使用 Git 管理文档
- 或使用 rsync/scp 同步文件

## 🔍 验证更新

编辑文件后，可以通过以下方式验证：

1. **查看容器日志**
   
   ```bash
   docker logs mkdocs | tail -20
   ```
   
   应该看到类似信息：
   
   ```
   INFO    -  Documentation built in 1.32 seconds
   INFO    -  [时间] Serving on http://0.0.0.0:8000/
   ```

2. **刷新浏览器**
   
   - 访问 http://101.43.95.130:8000
   - 按 F5 或 Ctrl+R 刷新
   - 应该看到最新内容

## ❓ 常见问题

### Q: 为什么不能在前端网站直接编辑？

A: MkDocs 是静态文档生成工具，它读取 Markdown 文件并生成静态 HTML 网站。前端只是展示，不提供编辑功能。

### Q: 如果我想在线编辑怎么办？

A: 可以考虑以下方案：

1. **使用 Wiki 系统**（如 Gitea 的 Wiki 功能）
2. **使用在线 Markdown 编辑器**（如 HackMD、StackEdit）
3. **使用 Git 工作流**（本地编辑 → Git 提交 → 服务器拉取）

### Q: 编辑后多久能看到更新？

A: 在开发模式下，保存文件后几秒钟内就会自动更新，刷新浏览器即可看到。

### Q: 需要重启服务吗？

A: 不需要！MkDocs 开发模式会自动检测文件变化并重新生成网站。

## 📚 相关资源

- [Markdown 语法指南](https://www.markdownguide.org/)
- [MkDocs 官方文档](https://www.mkdocs.org/)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)

---

**总结：MkDocs 需要编辑 Markdown 文件，不能在前端网站直接编辑。编辑文件后，MkDocs 会自动生成更新的网站。**