这个博客是怎么搭起来的:架构、内容流程与发布方式
用视觉笔记的方式拆解这个个人博客:为什么选择静态架构、内容如何组织、文章怎样发布,以及 Agent 在写作维护中的位置。
这个博客的核心选择很朴素:先把内容、页面和发布链路做稳,再考虑更复杂的后台能力。
它不是一个完整 CMS,也不是动态应用。文章是仓库里的 Markdown / MDX 文件,Astro 在构建期生成静态页面,GitHub Actions 再把产物发布到 GitHub Pages。
概览
构建后发布静态文件,不需要常驻后端。
文章放在 src/content/posts/。
Actions 构建,Pages 托管。
辅助写作、审查和结构整理。
为什么这样搭
这个博客要解决的是“长期沉淀”,不是一次性展示。它主要承载生活判断、项目实践、系统教程、视觉实验和项目复盘类内容。
内容直接
新增文章就是新增文件,不需要打开后台或维护数据库。
- 普通文章用 Markdown
- 视觉笔记和图表文章用 MDX
结构稳定
frontmatter 决定文章如何进入列表、分类、标签和 RSS。
- 分类、标签自动聚合
- 草稿和私密内容有发布边界
发布简单
推送仓库后由 GitHub Actions 构建,再发布到 GitHub Pages。
- 不手动上传 dist
- 不维护服务器进程
适合 Agent
文章、规则和模板都在仓库里,Agent 可以直接阅读、修改和验证。
- 根据 docs/writing/BLOG_AGENT.md 写作
- 用 npm test 和 build 校验
架构
flowchart LR A[MD / MDX 文章] --> B[Astro 内容集合] B --> C[页面模板] C --> D[静态构建] D --> E[dist 产物] E --> F[GitHub Actions] F --> G[GitHub Pages] G --> H[读者访问]
内容文件进入 Astro 内容集合,构建后由 GitHub Pages 托管。
这套架构的边界很清楚:写作阶段处理内容,构建阶段生成页面,发布阶段只托管静态文件。
Astro
负责内容读取、页面生成和静态构建。
Starlight
提供文档站基础能力,也保留指南入口的扩展空间。
MDX
让文章可以插入 Astro 组件、卡片和 Mermaid 图表。
页面
站点不是单页应用,而是一组构建期生成的静态入口:首页负责导览,文章页负责阅读,分类和标签负责聚合。
flowchart TD Home[首页] --> Articles[文章列表] Home --> Projects[项目页] Home --> About[关于页] Home --> Search[顶部搜索] Articles --> Detail[文章详情] Articles --> Category[分类页] Articles --> Tag[标签页] Detail --> RSS[RSS] Search --> Detail
大部分入口都由文章 frontmatter 和内容集合驱动。
首页
展示主题方向、精选文章和项目记录,让读者快速知道这里写什么。
文章列表
按日期展示公开文章,并连接分类、标签和详情页。
详情页
渲染 Markdown / MDX 正文,同时展示标题、摘要、标签和目录。
顶部搜索
在导航栏里提供轻量搜索入口,不需要单独维护搜索页面。
内容模型
每篇文章开头的 frontmatter 是内容进入站点的入口。它不只是元信息,也决定文章是否公开、如何聚合、是否进入精选。
flowchart LR A[frontmatter] --> B[标题与摘要] A --> C[分类与标签] A --> D[草稿与私密边界] A --> E[精选与阅读时间] B --> F[文章卡片] C --> G[分类 / 标签页] D --> H[公开页面过滤] E --> I[首页展示]
页面不手工维护链接,而是从文章字段生成列表、详情、分类和标签。
draft: true 不进入公开页面。
private: true 不生成公开入口。
featured: true 可进入首页精选。
固定分类现在有四个:生活、实践、教程、视觉实验室。分类负责内容类型,标签负责细粒度索引。
写作
写作流程尽量短:先选主题和分类,再写 frontmatter,最后用 Markdown / MDX 组织正文。
写作判断
普通笔记用 Markdown;需要卡片、图表或高亮说明时用 MDX。
技术文章优先写成视觉笔记:结论、指标、流程、模块、检查清单。
新文章默认 draft: true,只有明确确认发布后才改为 false。
发布
发布流程也保持文件化:文章进入仓库,本地验证通过后提交推送,GitHub Actions 负责构建和发布。
flowchart LR A[写文章] --> B[检查 frontmatter] B --> C[npm test] C --> D[npm run build] D --> E[提交并推送] E --> F[GitHub Actions] F --> G[GitHub Pages] G --> H[线上博客]
本地只负责写作和验证,线上由 GitHub Actions 发布到 GitHub Pages。
本地验证
用测试和构建确认内容边界、页面结构和 MDX 语法没有破坏站点。
npm testnpm run build
静态托管
线上托管的是构建后的 dist 文件,不需要 Node 服务、数据库或后台进程。
- 访问地址:/
- 发布来源:GitHub Actions
Agent 角色
Agent 不是发布系统本身,而是写作和维护流程里的协作者。它适合做结构整理、规则检查、图表补全和构建验证。
写作助手
把草稿整理成视觉笔记,补齐标题、摘要、卡片和流程图。
规则审查
检查分类、草稿状态、敏感信息、frontmatter 和发布边界。
构建验证
运行项目已有命令,确认文章能被 Astro 正常构建。
静态取舍
这个博客没有数据库、登录、评论和后台权限。它牺牲的是在线编辑便利性,换来的是低维护成本、可版本化内容和稳定访问。
静态博客
适合个人写作、版本管理、低成本部署和长期维护。
- 复杂度主要在构建期
- 线上访问链路短
- 内容变更有 Git 记录
动态博客
适合多人后台、权限系统、评论互动和复杂查询。
- 需要维护运行时服务
- 需要数据库和权限模型
- 当前阶段收益不够高
后续
后续演进会围绕写作体验和阅读体验逐步做,而不是一开始就扩成庞大系统。
演进顺序
保持分类稳定,继续把生活、实践、教程和视觉实验室文章写下去。
根据真实文章数量优化搜索、相关文章、系列文章和移动端阅读体验。
需要时再加入链接检查、图片资源检查和更细的 frontmatter 校验。