Publishing Setup · 把这个 repo 渲染成公开美化版站点¶

设置完成后，每次 push 到 agent-landscape 或 main 分支，站点会自动重建并部署。

三种 hosting 选项——根据 repo 是否 public 选第一种或后两种。

文件清单（已配置）¶

mkdocs.yml — MkDocs Material 主配置
index.md — 站点首页
assets/extra.css — 视觉打磨样式
.github/workflows/deploy.yml — 自动构建 + 部署

本地预览¶

cd alpha-search-frontier-notes
pip install mkdocs-material pymdown-extensions
mkdocs serve
# 浏览器打开 http://127.0.0.1:8000

Hosting 选项¶

Option A · GitHub Pages（如果 repo 是 public 或你有 GitHub Pro）¶

仓库设置启用 Pages：
GitHub repo → Settings → Pages
Source: GitHub Actions（不是 Deploy from a branch）
Save
Push 触发部署：
任何 push 到 agent-landscape 或 main → Actions tab 看到 build 跑起来
完成后访问 https://paulweng.github.io/alpha-search-frontier-notes/
自定义域名（可选）：
在 Settings → Pages 填 custom domain
Repo 加 CNAME 文件
DNS 加 CNAME record 指向 paulweng.github.io

Cost: 公开 repo 免费；私有 repo 需要 GitHub Pro ($4/月)。

Option B · Cloudflare Pages（推荐，private repo 也免费）¶

登录 Cloudflare Dashboard
Workers & Pages → Create application → Pages → Connect to Git
授权访问 GitHub alpha-search-frontier-notes repo
Setup：
Production branch: agent-landscape
Build command: pip install mkdocs-material pymdown-extensions && mkdocs build --site-dir _site
Build output directory: _site
Environment variables: PYTHON_VERSION=3.11
Save and Deploy → 几分钟后给你 alpha-search-frontier-notes.pages.dev 域名
Custom domain（可选）：Settings → Custom domains → 加你的域名

优势： - ✅ 完全免费（不限 private/public） - ✅ 全球 CDN，比 GitHub Pages 快 - ✅ 自定义域名免费 + 自动 HTTPS - ✅ Preview deployments（每个 branch / PR 自动出预览） - ✅ 不需要改 GitHub Actions

注意：Cloudflare Pages 直接读 repo 构建，不依赖 .github/workflows/deploy.yml。但 workflow 留着不影响（可以同时部署 GitHub Pages 和 Cloudflare Pages）。

Option C · Netlify / Vercel（同 Cloudflare 类似）¶

Netlify： - 登录 netlify.com → New site from Git → 选 repo - Build command: pip install mkdocs-material pymdown-extensions && mkdocs build - Publish directory: site（mkdocs 默认） - 给你 random-name.netlify.app 域名

Vercel： - 登录 vercel.com → Import Git repo - Framework preset: Other - Build: pip install mkdocs-material pymdown-extensions && mkdocs build - Output: site

三者择一即可——Cloudflare Pages 在 private repo + 性能 + 免费上是最优选。

部署后建议¶

给同事 / 老师分享¶

不要发 GitHub repo 链接（他们看到 raw markdown 文件列表）。发部署后的站点链接：

https://paulweng.github.io/alpha-search-frontier-notes/ (GitHub Pages)
https://alpha-search-frontier-notes.pages.dev (Cloudflare)
或你的 custom domain

站点有完整 search / nav / 移动端 / 暗色模式，对方体验远好于 GitHub。

权限控制¶

GitHub Pages on public repo: 站点全网公开
GitHub Pages on private repo (with Pro): 站点也是 public 的（Pages 不支持私有 site）
Cloudflare Pages: 默认 public；想加密码访问需要 Cloudflare Access（Zero Trust，免费 plan 支持 50 用户）

如果内容不想全公开，最简单的方式： 1. 用 Cloudflare Pages 部署 2. 启用 Cloudflare Access (Zero Trust 免费 plan) 3. 配置只允许 specific email allowlist（你 + 老师 + 同事）访问

持续更新流程¶

# 写新内容
git checkout agent-landscape
# 编辑 .md 文件 ...

# 本地预览
mkdocs serve

# Push 触发部署
git add .
git commit -m "Add new note on X"
git push

# Hosting 平台自动重新部署，1-2 分钟后线上更新

升级路径：Quartz (graph view + backlinks)¶

如果你后续想要 Obsidian-style graph view + 自动 backlinks，可以在另一个分支试 Quartz v4：

git checkout -b quartz-experiment
npx quartz create
# ... 配置 ...

Quartz 视觉更"研究花园"风格，但 setup 略复杂。建议先用 MkDocs Material 稳定运行 1-2 周再考虑切换。

Q&A¶

Q: 中文渲染好不好？ A: Material 主题原生支持中文，配置里 search.lang 加了 zh 让搜索分词更准。

Q: 数学公式？ A: 已经配 MathJax，写 $E = mc^2$ 或 $$ ... $$ 直接渲染。

Q: PPT 和 PDF 怎么办？ A: 二进制文件不进 nav，但 repo 里可以直接 download。如果想 embed PDF preview，加 <iframe src="..."> 即可。

Q: 我能 self-host 吗？ A: mkdocs build 后 site/ 目录就是完整静态文件，扔任何 web server（Nginx / Caddy / S3+CloudFront）都行。

Q: 改主题颜色？ A: 改 mkdocs.yml 里 palette 配置；细节改 assets/extra.css。

End of publishing guide. 站点 stack：MkDocs Material + GitHub Actions (or Cloudflare Pages) + pymdown-extensions。技术堆栈极简，未来维护负担最小。