这个博客是怎么搭起来的：架构、内容流程与发布方式
把仓库、内容边界、规则索引、写作流程与静态发布放进一套博客系统蓝图，说明这个个人博客如何长期维护。
本文目录 6 节 · 点击展开
这个博客首先是一套可维护的内容系统，其次才是一组网页。文章、规则、索引和发布配置都留在仓库里，让一次写作从选题到公开都有清楚边界。
本篇回答“内容与维护系统怎么组织”；系列下一篇《从代码看这个博客》沿一次请求和构建，解释页面、Content Collections、MDX 与部署如何真正跑起来。
先看全局：仓库里有四条相互咬合的主线
内容线负责写什么，页面线负责怎么呈现，规则线负责如何维护，交付线负责怎样变成公开站点。
src/content/posts/正式文章和视觉实验都进入同一个 Content Collection，再由分类、标签、系列与公开状态组织。
*.mdx保存可版本化正文visual-lab/单独承载 Demo
src/pages/ + src/components/页面文件建立路由，组件与布局建立阅读界面；文章只调用真正需要的展示能力。
src/layouts/SiteLayout.astro提供外壳src/styles/global.css维护全局视觉
AGENTS.md + docs/入口文件提供路由与关键硬边界，开发、写作、视觉和内容索引分别在 docs 中保持单一权威来源。
llms.txt帮 Agent 快速判断入口CONTENT_INDEX.md限定参考范围
astro.config.mjs + .github/workflows/Astro 在构建期生成静态文件；Actions 在 main 推送或手动触发后构建，再交给 Pages。
package.json暴露验证命令dist/是构建产物，不是内容源
这张地图刻意不展开函数和模板细节。维护者先判断“我在改内容、页面、规则还是交付”，就能避免把写作规范塞进组件、把 Demo 混进正式文章，或把构建产物当源码维护。
正式文章、视觉实验和规则文档为什么必须分区
目录边界不是为了整齐，而是让读者内容、设计试验和 Agent 规则不会互相污染。
src/content/posts/*.mdx面向读者发布。每篇保留完整 frontmatter，分类只使用生活、实践、教程、视觉实验室中的合法值。
规则不作为文章发布
src/content/posts/visual-lab/集中测试组件、复杂排版和视觉模式。它提供参考效果，但不会成为正式文章的固定骨架。
正文不复制规则全文
AGENTS.md · docs/ · llms.txt只服务维护与 Agent 路由。详细规则进入 docs，AGENTS.md 保留硬规则，llms.txt 提供快速入口。
规则和索引如何组成维护控制面
Agent 不需要默认通读整个仓库，而是从任务类型进入最小必需上下文。
先辨认是代码、文章、MDX 视觉还是内容检索。
AGENTS.md / llms.txt给出读取顺序与硬边界，不承载长示例。
docs/DEV_RULES.md最小改动、验证与 Git 约定
docs/writing/写作、风格与内容索引
docs/ARTICLE_VISUAL_SYSTEM.md整页视觉方案与章节闭环
CONTENT_INDEX.md先选主题，再只读 1 到 3 篇正文
这套控制面让 Agent 可参与维护，但不会把 Agent 变成新的内容源。作者事实和项目真实代码仍然是依据；规则只约束怎样读取、修改和验证。
一篇文章怎样从想法进入公开内容系统
新文章默认 draft: false、private: false；只有用户明确要求草稿或私密时才切换状态。
- 01 · BRIEF确认主题与读者任务
提炼一句话结论、事实素材、专业风格和文章形态。
产出：视觉简报 - 02 · DESIGN先设计网页作品
按读者问题拆 H2；系统、教程和流程文章默认一章一张完整信息图。
产出：章节蓝图 - 03 · WRITE写入 Content Collection
正文进入
产出：MDX 文件src/content/posts/，frontmatter 对齐 schema 与固定分类。 - 04 · VERIFY检查事实与页面
审查敏感信息、桌面和移动布局，再执行测试与静态构建。
产出：可构建页面 - 05 · PUBLISH提交到 main 的发布链
推送触发 Actions；线上是否已经更新，必须查看实际运行后才能确认。
产出：静态站点
draft: false · private: false文章通过内容与页面检查后进入公开集合。
draft: true不进入公开页面；何时公开由用户后续决定。
private: true不进入公开列表、详情、RSS 与站内搜索数据；它不是密码保护。
仓库怎样变成 GitHub Pages 上的静态站点
当前配置使用 Astro + MDX。工作流在 main 推送或手动触发时运行，构建完成后由 GitHub Pages 托管静态产物。
posts · pages · components · stylesGit 记录内容与代码的每次变化。
npm test
npm run build测试与构建验证由本地或 CI 执行。
withastro/action@v6上传 Pages artifact，deploy job 等待 build。
https://apexcheng.github.io提供静态文件，不运行应用后端。
site 已配置，未配置 base这与当前用户站点根路径方案一致。
contents: read、pages: write、id-token: write，并使用 pages concurrency group。
这些属于仓库外实时状态，不能只凭配置文件宣称已经成功。
静态架构的取舍也在这里：它没有数据库、登录、在线编辑后台和常驻应用服务，换来的是更短的访问链、更低的运行维护成本，以及可被 Git 审查的内容历史。
两篇蓝图应该怎样配合阅读
两篇共享同一套蓝图语汇，但不会重复同一张图：一篇解释“为什么这样组织”，一篇解释“代码怎样执行”。
适合新增文章、维护规则、调整内容边界或理解发布责任时阅读。
- 仓库职责地图
- 正式文章 / Demo / docs 分区
- 写作到公开的控制链
适合按 URL 找页面、追踪文章渲染、理解构建产物或排查部署链路时阅读。
- 页面与路由定位
- Collection / MDX / Layout 渲染栈
- 本地与 Actions 双运行链