Files

T

kurihada 155b347d3f docs: 新增 MkDocs 部署文档

涵盖 MkDocs Material 配置、构建流程、Caddy Docker 部署、完整工作流和维护指南

2026-06-04 11:46:27 +08:00

4.1 KiB

Raw Blame History

MkDocs 知识库部署

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

架构

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 要点

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 本地构建

cd ~/kb && mkdocs build

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

2.2 本地预览

mkdocs serve -a 0.0.0.0:8000

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

2.3 Git 工作流

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

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

三、Caddy 部署

3.1 docker-compose.yml

Caddy 部署在 ~/docker/caddy/：

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 的配置

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 部署文档）
handle { ... } — 包裹 file_server，保证和 handle_path 互斥
Caddy 自动申请和续期 Let's Encrypt TLS 证书，无需额外配置

3.3 部署后重载

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

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

检查构建状态

cd ~/kb && mkdocs build --verbose

DNS 与 TLS

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

Caddy 日志

docker logs caddy | grep note.kurihada.com

4.1 KiB Raw Blame History Unescape Escape