改官网
你正在看的这个站在仓库的 site 目录里：Astro 生成的纯静态页。这一篇说内容放在哪、三个区各有什么规矩、截图和小演示从哪来、提交之前跑什么。
跑起来
cd site && npm ci
npm run dev
npm run build
npm run dev 是开发服务器，改了马上看到；npm run build 是正式构建，产物在 site/dist/，最后一步用 Pagefind 生成搜索索引。要 Node 22.12 以上。
内容放在哪
- 大纲：
site/src/data/outline.ts。三个区（用、懂、改）的分组、编号、标题只写这一处：顶栏、三个封面、首页、文档页左边的目录都从这里读。大纲里列了的必须写好，写好了的必须在大纲里。 - 文档：
site/content/docs/<区>/<名字>.mdx。开头写number（和大纲对上）、lead（标题下面那一段）、verified（和源码对过的日期、提交、依据的文件）；「用」的页还要写minutes。 - 站内链接：写成
[1.21](/use/its-day/)或[1.21 看看它今天在干什么](/use/its-day/)。编号要和那一页对上，测试会查。
三个区的规矩
构建时查，不合规矩构建失败：
- 用：写给没写过代码的人。最后一节是「下一步」；不放「对应的代码」；要写
minutes；正文里不出现文件名、函数名、配置键名（tests/test_site.py查）。 - 懂：讲道理，代码只放在倒数第二节「对应的代码」，最后一节是「没做到的」。
- 改：最后一节是「没做到的」。
侧注用 <Note kind="why">（为什么）或 <Note kind="mind">（注意），和它注的那一段一起包进 <Annotated>，侧注写在前面；一页最多三条。
组件
<Steps>：包住一个有序列表，一步一个动作，先写做什么、再写会看到什么。<Shot>：软件截图，写上截图的名字（name）和给读屏的说明（alt）。浅色深色各一份，跟着页面换；直接放在正文里的会跨进右边那一栏。<SendDemo>、<Cleaned>：首页和 2.8 的小演示，数据是跑真函数导出的。<ConfigReference>：配置项参考的那张大表，从配置的定义生成（3.21）。
截图和小演示从哪来
- 截图由
scripts/site_shots.py在假数据上截，不手截、不截真数据：它自己开起网页后台的假数据服务（scripts/ui_fixture_server.py --docs，官网用的那一份）、网页后台的前端和桌面版的模拟壳，截完关掉。截好的图放进site/public/shots/，尺寸写进site/src/data/shots.json。点一张截图会在新标签页打开原图，手机上可以放大看。 - 假数据要和正文对得上：按真的默认配置（作息几点睡、每类活动的优先级），一天按钟点排，一个页面上互相对照的数一致。截图里看得见的，正文就得说得通。
- 首页的句子和小演示：
scripts/site_demo_export.py跑真函数导出到site/src/data/site-data.json，不手改；不是最新的，测试会红。 - 颜色、时长、字号都用
design/src/tokens.css的令牌；样式里写死颜色或时长，测试会红。 - 网站图标：
scripts/site_icons.py照令牌画出site/public/里的三份（标签页用的 SVG、不认 SVG 的浏览器用的.ico、苹果设备加到主屏幕用的 PNG），不手改；令牌的颜色改了，测试会红。
提交之前
在 site/ 里构建：
npm run build
再在仓库根目录：
.venv/bin/python -m pytest tests/test_site.py
.venv/bin/python scripts/site_check.py
scripts/site_check.py 把构建好的站开在本机，用无头 Chrome（要装 Chrome 或 Chromium）把每一页按手机和电脑的几种尺寸打开，查看得见的错：页面被撑宽、字被裁掉或压在一起、点的地方太小、跳到小节时标题被顶栏挡住、图片坏了；按手机打开时还查整页有没有被缩小、输入框的字是不是小到 iPhone 一点进去就放大。再分浅色深色量文字对比度。有问题退出码是 1。--phone 只按手机查，竖屏横屏都有；--widths 按自己给的几种宽度查。
哪几页该重新核对：.venv/bin/python scripts/site_stale.py 列出页头「最后核对」里的文件在核对之后又改过的页。核完一页，把它的 verified 改成当天的日期和提交。再过一遍 3.4 的关卡。
上线
站放在 Cloudflare Pages 上，传上去的就是 site/dist/。构建完，site/scripts/deploy-files.mjs 还会在里面写四份文件，都从构建出来的页面算，不手写：
_headers：Cloudflare Pages 照它给每个响应加头。内容安全策略只认本站：脚本、样式、图片、字体、请求都不能来自别的网站；内联脚本只放行构建时算出哈希的那几段，改了内联脚本，重新构建就跟着变；站内搜索要跑 WebAssembly，单独放行。另外：别的网站不能用框架嵌这个站；site/dist/_astro/里的文件名带内容哈希，浏览器存一年；Cloudflare 给的pages.dev备用地址不让搜索引擎收。sitemap.xml、robots.txt：给搜索引擎的页面清单。third-party-licenses.txt：网页里带着 Astro（换页）和 Pagefind（站内搜索）的代码，附上它们的许可证原文。
正式地址只写在 site/astro.config.mjs 的 site，每一页的规范链接（canonical）和 sitemap 都从它来。scripts/site_check.py 开站时带着同一份 _headers，被安全策略拦下的东西算报错：本机查过是什么样，上线后就是什么样。
没做到的
- 截图不会跟着界面变：网页后台、桌面版改了样子，要自己重截。
- 过期的页不会让测试变红：代码改了以后，要自己跑
site_stale.py、回来对一遍。 - 搜索只按字面找：意思一样、说法不同的搜不到。
- 安全策略放行 WebAssembly 用的是
'wasm-unsafe-eval'，比这旧的浏览器不认（Safari 16、Chrome 97、Firefox 102 以前，都是 2022 年的版本）：在这些浏览器里站内搜索用不了，别的照常。