个人笔记发布流程：Obsidian → MkDocs Material → Cloudflare Pages

这个项目把同一个目录同时作为 Obsidian Vault 和 MkDocs 项目使用，不维护第二份笔记副本。

D:\public-pages\public-pages\dev-pages
├── mkdocs.yml
├── docs\       ← Vault 内唯一的 Markdown 笔记源
│   ├── index.md
│   ├── cs\
│   ├── quant\
│   └── ...
└── site\       ← MkDocs 生成的静态文件，可随时删除并重建

日常更新

在 Obsidian 中直接编辑 docs/ 下的 Markdown 文件。.obsidian/ 只保存本地编辑器设置，不应发布到网站。笔记之间优先使用标准 Markdown 链接，例如 [机器学习](cs/ml.md)；Obsidian 的 [[Wiki Link]] 在静态网站中不会自动变成可靠链接，发布前需要检查。

在个人电脑上运行 dry-run：

cd D:\public-pages\public-pages\dev-pages
.\.venv\Scripts\python.exe scripts\scan_sensitive.py docs
.\.venv\Scripts\python.exe scripts\publish.py --root . --dry-run

dry-run 会扫描可能的 API key、Token、私钥、凭据 URL 和敏感文件，执行 mkdocs build --strict，检查生成 HTML/CSS 中的链接、图片、锚点和静态资源。任何阻塞错误都会停止流程，也不会使用上一次的 site/ 作为回退版本。

本地预览：

.\.venv\Scripts\python.exe -m mkdocs serve --dev-addr 127.0.0.1:8000

打开 http://127.0.0.1:8000/，检查导航、全文搜索、代码块、图片、移动端布局和下载文件。确认公开内容无误后，再进行部署。

Cloudflare Pages Direct Upload

Cloudflare Pages 接收已经构建好的 site/ 静态目录。认证和上传只在个人电脑进行，公司电脑不需要登录 Cloudflare，也不需要安装任何同步客户端。

首次配置（个人电脑）：

npm install --save-dev wrangler@4
npx wrangler login
npx wrangler pages project create <project-name> --production-branch main

部署前必须完成本地预览，并明确确认内容可以公开：

.\.venv\Scripts\python.exe scripts\publish.py `
  --root D:\public-pages\public-pages\dev-pages `
  --project <project-name> `
  --branch main `
  --preview-reviewed `
  --confirm-public

等价的 Wrangler 命令是：

npx wrangler pages deploy site --project-name <project-name> --branch main

发布后的地址通常是：

https://<project-name>.pages.dev

公司电脑只做以下操作：

打开 Chrome 或 Edge
访问公开 HTTPS 地址
阅读、搜索、复制

如果公司策略禁止访问 pages.dev 或该类公共托管服务，不能用隐藏域名、代理、隧道、DNS 技巧或其他方式规避限制。应停止这个流程并寻找公司批准的访问方式。

公开内容的边界

Cloudflare Pages 上的内容应当被视为任何互联网用户都能读取、下载、缓存、索引和再分发。robots.txt、noindex、隐藏导航和不易猜的 URL 都不是访问控制。不要发布密码、访问令牌、私钥、个人日记、财务记录、雇主机密、NDA 内容或没有再分发权的文件。

自动扫描只能减少明显错误，不能替代人工审阅。发现真实凭据时，应先撤销或轮换凭据，再处理笔记内容。