网站构建与部署（Zensical → Cloudflare Pages）¶

这套资料的所有正文都在仓库的 Markdown / .py 文件里；网站只是把它们渲染成带导航、搜索、代码高亮和深色模式的静态页面。构建工具是 Zensical（Material for MkDocs 团队的继任项目，Python 包，用 uv 安装），产物是 site/ 目录下的纯静态文件，拖到 Cloudflare Pages 即可。

一、日常流程（改了文档之后）¶

# 1. 本地预览（自动打开浏览器，Ctrl+C 停止）
uv run zensical serve -o

# 2. 生成静态站到 site/（--clean 清缓存，稳妥）
uv run zensical build --clean

# 3. 打开 Cloudflare 控制台，把 site/ 文件夹拖进去（见第三节）

什么时候需要多跑一步 uv run python tools/gen_site_pages.py：只有在新增 / 删除 / 重命名了 exercises/ 下的练习文件，或新增了顶层文档时。因为 docs/ 里的页面只是"薄包装"——例如 docs/plan/day1.md 的全部内容就是一行 --8<-- "plan/day1.md"，构建时才把原文件引进来；练习代码页则是按文件列表生成的。改动已有文件的内容不需要重新生成。

新增顶层文档还要在 zensical.toml 的 nav 里加一行，否则页面能访问但不在左侧导航出现。

二、第一次准备（已经做好，记录在此）¶

事项	状态
`uv add --dev zensical`	已加入 `pyproject.toml`（`zensical==0.0.59`，锁在 `uv.lock`）
`zensical.toml`	仓库根目录；中文界面、不加载 Google 字体、代码复制按钮、深浅色切换、顶部标签栏、snippets 根路径 = 仓库根
`docs/stylesheets/extra.css`	布局微调：视口 ≥1440px 时内容容器放宽到 100rem（≈2000px，1080p/2K 屏等同全屏，4K 封顶）；代码字号 0.853em → 0.9em。想改回默认宽度删掉这个文件里的 `@media` 块即可
`docs/` 薄包装页	`tools/gen_site_pages.py` 生成（`stylesheets/` 是手写的静态文件，脚本不会动它）
`site/`、`.cache/`	已加入 `.gitignore`，是构建产物

换一台电脑时：装好 uv → 克隆/复制仓库 → uv sync → 上面三条命令即可。

三、手动上传到 Cloudflare Pages（拖拽方式）¶

登录 Cloudflare 控制台 → 左侧 Workers & Pages → Create → 选 Pages 标签 → Upload assets（"Direct Upload"）。
填项目名（例如 learn-python），点 Create project。
把本地的 site/ 文件夹整个拖进上传框（是拖 site 这个文件夹，不是它里面的文件一个个拖，也不是拖整个仓库）。
点 Deploy site。几十秒后得到 https://learn-python.pages.dev/（项目名不同则地址不同）。
把这个地址填回 zensical.toml 的 site_url，下次构建时 sitemap 与页面的 canonical 链接就正确了（不填也能正常访问）。

之后每次更新：进入该项目 → Create a new deployment → 选 Production → 再拖一次 site/ → Save and Deploy。

限制（官方数据）：拖拽上传最多 1,000 个文件、单文件 ≤ 25 MiB；本站约 80 个文件、几 MB，远低于上限。若以后超过 1,000 个文件，改用第四节的命令行方式（上限 20,000 个文件）。

国内访问：*.pages.dev 域名在国内访问有时不稳定。若遇到打不开或很慢，在项目的 Custom domains 里绑定一个自己的域名（域名的 DNS 需托管在 Cloudflare）即可解决；这不影响现在先用默认域名。

四、可选：一条命令部署（wrangler）¶

本机已有 Node.js（v23），可以不进控制台：

npx wrangler login                                     # 第一次：浏览器授权
npx wrangler pages deploy site --project-name=learn-python

--project-name 用第三节创建的项目名；也可以让 wrangler 帮你新建。之后更新就是"uv run zensical build --clean + 上面第二条命令"。

五、网站里各页面对应的原文件¶

网站页面	原文件	说明
总览与知识地图	`README.md`
三天计划 Day 1/2/3	`plan/day1.md` `day2.md` `day3.md`
AI 使用指南	`ai-guide.md`
打卡与自评	`checklist.md`	网页只读；打卡在本地文件里做
周一项目规格	`project/README.md`
练习骨架（只读）	`exercises/day1/.py`、`exercises/day2/*`	带行号的只读代码页，方便手机看题
答案（默认折叠）	`exercises/solutions/**`、`exercises/solutions/quiz_answers.md`	每个文件一个折叠块，点击才展开
调研报告	`research/*.md`
网站构建与部署	`deploy.md`（本页）

六、已知限制与注意事项¶

Zensical 仍是 0.0.x（本站用 0.0.59，2026-09-03 发布），版本迭代很快。已用 uv.lock 锁定版本，uv sync 不会自动升级；想升级用 uv lock --upgrade-package zensical 后重新 build 并检查页面。若某次升级后构建失败，uv lock 回退即可。
搜索界面目前只有英文提示（Zensical 官方说明：搜索引擎是全新实现，尚未本地化），中文内容可以搜索。
Material for MkDocs（Zensical 的前身）将于 2026-11-05 停止维护；本站没有依赖它。
网页中的复选框、日志模板都是只读展示；真正的打卡在 checklist.md。
pymdownx.snippets.check_paths = true：如果某个被引入的文件被移动或改名，构建会直接报错而不是默默留空——这是故意的，看到报错就去更新 tools/gen_site_pages.py 或 nav。
网站不请求任何外部资源（字体、CDN、统计），可离线打开 site/index.html（部分功能如搜索需要通过 HTTP 访问，用 uv run zensical serve 即可）。