# MkDocs 知识库部署

> `note.kurihada.com` — 基于 MkDocs Material 的个人知识库，Caddy 静态文件服务。

---

## 架构

```mermaid
graph LR
    Repo["~/kb Git 仓库"]
    Build["mkdocs build"]
    Site["kb/site/ 静态文件"]
    Caddy["Caddy Docker<br/>caddy:alpine"]
    Browser["浏览器<br/>note.kurihada.com"]

    Repo --> Build --> Site -->|"bind mount :ro"| Caddy --> Browser
```

整个流程：编辑 Markdown → `mkdocs build` 生成静态文件 → Caddy 直接 serve。

---

## 一、MkDocs 配置

### 1.1 mkdocs.yml 要点

```yaml
site_name: 我的知识库
theme:
  name: material
  language: zh
  features:
    - navigation.instant      # SPA 即时加载
    - navigation.tabs         # 顶部标签
    - navigation.indexes      # 分类文件夹可点击
    - search.suggest          # 搜索建议
    - content.code.copy       # 代码块复制按钮
  custom_dir: docs/overrides  # Artalk 评论等自定义模板

markdown_extensions:
  - pymdownx.superfences:     # Mermaid 流程图支持
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
```

### 1.2 目录结构

```
~/kb/
├── mkdocs.yml              # 站点配置
├── docs/                   # Markdown 源文件
│   ├── index.md
│   ├── overrides/          # 主题覆盖（评论系统等）
│   │   └── partials/
│   │       └── comments.html
│   ├── 技术/
│   ├── 旅行/
│   ├── 摄影/
│   ├── 3D打印/
│   └── 日记/
├── site/                   # 构建输出（.gitignore 忽略）
└── .gitignore
```

---

## 二、构建

### 2.1 本地构建

```bash
cd ~/kb && mkdocs build
```

输出到 `site/` 目录，耗时 < 1 秒。

### 2.2 本地预览

```bash
mkdocs serve -a 0.0.0.0:8000
```

浏览器打开 `http://localhost:8000`，修改 Markdown 后自动刷新。

### 2.3 Git 工作流

```bash
cd ~/kb
mkdocs build                 # 构建
git add -A
git commit -m "描述改动"      # 提交 Markdown 源码
```

> `site/` 已在 `.gitignore` 中忽略，只提交 Markdown 源文件。

---

## 三、Caddy 部署

### 3.1 docker-compose.yml

Caddy 部署在 `~/docker/caddy/`：

```yaml
services:
  caddy:
    image: caddy:alpine
    container_name: caddy
    restart: unless-stopped
    networks:
      - nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./data:/data                         # TLS 证书存储
      - /home/kurihada/kb/site:/srv/mkdocs:ro  # kb 静态文件

networks:
  nginx:
    external: true
```

### 3.2 Caddyfile 中 kb 的配置

```caddy
note.kurihada.com {
    handle_path /artalk* {
        reverse_proxy artalk:23366
    }
    handle {
        root * /srv/mkdocs
        file_server
    }
}
```

列一下关键点：

- `root * /srv/mkdocs` — 指向挂载进来的 `site/` 目录
- `handle_path /artalk*` — Artalk 评论系统反代（详见 [Artalk 部署文档](artalk评论系统.md)）
- `handle { ... }` — 包裹 `file_server`，保证和 `handle_path` 互斥
- Caddy 自动申请和续期 Let's Encrypt TLS 证书，无需额外配置

### 3.3 部署后重载

```bash
docker restart caddy
```

---

## 四、完整工作流

```
1. 编辑 docs/ 下的 Markdown
2. mkdocs build            # 生成 site/
3. git add -A && git commit # 提交源码
4. (无需重启 Caddy)         # site/ 通过 bind mount 实时生效
```

> 因为 Caddy 通过 `bind mount` 直接读取 `~/kb/site/`，`mkdocs build` 后变更即时生效，无需重启任何服务。

---

## 五、维护

### 升级 MkDocs Material

```bash
pip install --upgrade mkdocs-material
mkdocs build                # 确认构建无报错
```

### 检查构建状态

```bash
cd ~/kb && mkdocs build --verbose
```

### DNS 与 TLS

- DNS：`note.kurihada.com` A 记录指向服务器 IP
- TLS：Caddy 自动通过 Let's Encrypt 申请，90 天自动续期
- 证书存储：`~/docker/caddy/data/`

### Caddy 日志

```bash
docker logs caddy | grep note.kurihada.com
```