这个站点没有后台、没有数据库、没有构建服务器。整个更新流程只有三步：

  1. 在 content/posts/ 里新建一个 Markdown 文件
  2. 运行 python build.py 生成本地页面
  3. 运行 bash publish.sh 推到 Cloudflare

为什么不用手改 HTML

一开始确实是几个手写的 HTML 页面。但每加一篇文章，就得同时改四处：文章页本体、首页列表、sitemap.xml、feed.xml。改漏一处不会报错，只会安静地坏掉——RSS 里少一篇文章，或者首页列表永远停在三个月前。

所以改成内容与模板分离：Markdown 是唯一的内容源，HTML 是生成物。生成物（public/ 目录）不进 Git，随时可以整个删掉重新生成。

目录结构

blog/
├── content/
│   ├── posts/          每一篇文章一个 .md
│   └── about.md        关于页
├── templates/
│   └── layout.html     页面外壳（head、页头、页脚）
├── static/             需要原样拷过去的东西
│   ├── css/style.css
│   ├── _headers
│   └── favicon.svg
├── public/             生成结果，只有这个目录会被部署
├── build.py            生成器，只用 Python 标准库
├── publish.sh          构建 + 部署
└── site.json           站点名、域名、首页文案

写一篇新文章

新建 content/posts/2026-11-12-hello.md：

---
title: 文章标题
date: 2026-11-12
summary: 一句话摘要，会显示在首页列表和 RSS 里。
tag: 随笔
draft: false
---

正文从这里开始，支持标题、列表、表格、代码块、引用。

文件名开头的日期决定排序，后面的部分是 URL：这个文件会生成 public/post-hello.html，对外地址是 /post-hello（Pages 会自动去掉 .html）。

draft: true 的文章默认不生成，本地想预览草稿就运行 python build.py --drafts。

发布

python build.py      # 只构建，生成到 public/
bash publish.sh      # 构建 + 上传到 Cloudflare Pages

publish.sh 里其实就两行：跑一次 build.py，然后跑 wrangler pages deploy public。项目名写在脚本顶部的变量里。

Windows 上也可以直接双击 publish.cmd。

让 AI 来写

这套结构是专门为「AI 写、人来发」设计的。对 AI 只需要说一句话：

帮我写一篇关于 xxx 的文章，加到博客里，然后发布。

AI 要做的动作是固定的：新建一个带 front matter 的 Markdown 文件、跑 build、跑 publish。不需要它去理解 HTML 结构，也就不会把首页列表改坏。

具体规则写在仓库根目录的 AGENTS.md 里，任何 AI 工具进到这个目录都能读到。

几个注意点

  • public/ 不要手改，下次构建会被覆盖
  • 图片放 static/assets/，Markdown 里写 /assets/xxx.jpg（根路径，不是相对路径）
  • 改配色改字号：只动 static/css/style.css
  • 改站点名、域名、首页文案：只动 site.json
  • 换了域名：site.json 里的 baseUrl 改掉，重新 build，RSS 和 sitemap 里的链接会自动跟着变