doc.kabin.fun 建站手册¶

架构总览¶

Obsidian/工作/ (源文件)
  │  mkdocs-build.py 复制 + 过滤
  ▼
mkdocs-content/ (MkDocs 源目录)
  │  mkdocs build
  ▼
mkdocs-site/ (静态 HTML)
  │
  ├── localhost:8000 (MkDocs serve — 开发)
  └── Cloudflare Tunnel → doc.kabin.fun (生产)

关键文件¶

文件	作用
`/opt/data/mkdocs.yml`	MkDocs 配置 + 导航结构
`/opt/data/scripts/mkdocs-build.py`	内容复制 + 站点构建脚本
`/opt/data/mkdocs-content/`	构建源目录（自动生成，勿手动编辑）
`/opt/data/mkdocs-site/`	输出站点（自动生成）

导航规则¶

导航定义在 mkdocs.yml 的 nav: 段。

每个文件夹用 📋 索引.md 作为该目录的首页（含 type: index frontmatter）
导航标签 = 文件夹名（如 01-Projects），保持与 Obsidian 源一致
新增文件夹 → 在 mkdocs.yml nav 中手动添加条目
排除目录（不发布）：99-Archive, .obsidian, .trash, work-scripts, assets

构建命令¶

# 全量构建（清空 → 复制 → mkdocs build）
python3 /opt/data/scripts/mkdocs-build.py build

# 仅复制内容（不 build）
python3 /opt/data/scripts/mkdocs-build.py content

内容源¶

工作库：/opt/data/Obsidian/工作/ — 仅发布 _wiki/, 01-Projects/, 02-Reference/ 三个目录
生活库（苏子桐）：/opt/data/Obsidian/生活/苏子桐/ — 仅发布 融合画像/, _sops/, SYS_LOG.md, SYS_CHECKS.md, 苏子桐数字孪生系统.html
生活库 Wiki：/opt/data/Obsidian/生活/_wiki/ — 发布 concepts/, decisions/, moc/

自动重建¶

cron 任务 1c6ff77dc725「MkDocs 知识站自动重建」每 15 分钟自动执行。

排障¶

现象	原因	修法
导航标签空白	index 文件缺失或无标题	确认目录下有 `📋 索引.md`，且 frontmatter 有 `title:`
HTTP 530	Cloudflare 隧道断开	检查 `cloudflared` 进程，`python3 /opt/data/start_tunnel.py`
内容没更新	重建 cron 未到 / 构建失败	手动 `python3 /opt/data/scripts/mkdocs-build.py build`