mkdocs/部署说明.md

MkDocs 个人知识库部署说明

📋 简介

MkDocs 是一个基于 Markdown 的文档生成工具，使用 Material 主题提供美观的文档界面。

🚀 快速开始

1. 启动服务

cd /home/renjianbo/devops/mkdocs
docker-compose up -d

2. 访问地址

• 本地访问: http://localhost:8000
• 服务器访问: http://101.43.95.130:8000

3. 查看日志

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 中添加：

nav:
  - 新章节:
    - 新章节/内容.md

🔧 常用命令

启动服务

docker-compose up -d

停止服务

docker-compose down

重启服务

docker-compose restart

查看日志

docker-compose logs -f

构建静态站点

docker-compose exec mkdocs mkdocs build

构建后的静态文件会生成在 site/ 目录。

进入容器

docker exec -it mkdocs sh

📝 配置说明

修改站点信息

编辑 mkdocs.yml 文件：

site_name: 个人知识库
site_description: 个人技术文档和知识管理平台
site_author: renjianbo
site_url: http://101.43.95.130:8000/

修改主题

在 mkdocs.yml 的 theme 部分修改主题配置。

添加插件

在 mkdocs.yml 的 plugins 部分添加插件。

🎨 功能特性

• ✅ Material 主题: 美观现代的界面
• ✅ 全文搜索: 快速查找内容
• ✅ 响应式设计: 支持各种设备
• ✅ 深色模式: 支持主题切换
• ✅ 代码高亮: 支持多种编程语言
• ✅ 数学公式: 支持 LaTeX 公式
• ✅ 流程图: 支持 Mermaid 流程图

📚 使用技巧

代码块

使用三个反引号包裹代码，并指定语言：

```python
def hello():
    print("Hello, World!")

### 表格

```markdown
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 值1 | 值2 | 值3 |

图片

将图片放在 docs/images/ 目录，使用相对路径：

![图片描述](images/example.png)

内部链接

[链接文本](../其他文档.md)

外部链接

[链接文本](https://example.com)

🔍 故障排查

端口被占用

如果端口 8000 被占用，修改 docker-compose.yml 中的端口映射：

ports:
  - "8001:8000"  # 改为其他端口

页面不更新

1. 检查文件是否保存
2. 查看容器日志：docker-compose logs mkdocs
3. 重启服务：docker-compose restart

权限问题

确保文件有正确的权限：

chown -R renjianbo:renjianbo /home/renjianbo/devops/mkdocs

📖 相关资源

• MkDocs 官方文档
• Material for MkDocs
• Markdown 语法指南

💡 最佳实践

1. 定期备份: 定期备份 docs/ 目录和 mkdocs.yml
2. 版本控制: 使用 Git 管理文档
3. 文档组织: 按主题分类组织文档
4. 保持更新: 定期更新文档内容

---

开始编写你的文档吧！ 📝