系列 · 这个博客是怎么搭起来的 第 1 篇 / 共 3 篇 实践

这个博客是怎么搭起来的:架构、内容流程与发布方式

用视觉笔记的方式拆解这个个人博客:为什么选择静态架构、内容如何组织、文章怎样发布,以及 Agent 在写作维护中的位置。

作者:黄撑 更新于 2026-06-30

这个博客的核心选择很朴素:先把内容、页面和发布链路做稳,再考虑更复杂的后台能力。

它不是一个完整 CMS,也不是动态应用。文章是仓库里的 Markdown / MDX 文件,Astro 在构建期生成静态页面,GitHub Actions 再把产物发布到 GitHub Pages。

概览

站点类型 Static

构建后发布静态文件,不需要常驻后端。

内容源 MDX

文章放在 src/content/posts/。

发布链路 GitHub

Actions 构建,Pages 托管。

维护角色 Agent

辅助写作、审查和结构整理。

为什么这样搭

这个博客要解决的是“长期沉淀”,不是一次性展示。它主要承载生活判断、项目实践、系统教程、视觉实验和项目复盘类内容。

Write

内容直接

新增文章就是新增文件,不需要打开后台或维护数据库。

  • 普通文章用 Markdown
  • 视觉笔记和图表文章用 MDX
Build

结构稳定

frontmatter 决定文章如何进入列表、分类、标签和 RSS。

  • 分类、标签自动聚合
  • 草稿和私密内容有发布边界
Deploy

发布简单

推送仓库后由 GitHub Actions 构建,再发布到 GitHub Pages。

  • 不手动上传 dist
  • 不维护服务器进程
Agent

适合 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 托管。

这套架构的边界很清楚:写作阶段处理内容,构建阶段生成页面,发布阶段只托管静态文件。

Core

Astro

负责内容读取、页面生成和静态构建。

Docs

Starlight

提供文档站基础能力,也保留指南入口的扩展空间。

Writing

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 是内容进入站点的入口。它不只是元信息,也决定文章是否公开、如何聚合、是否进入精选。

frontmatter 驱动
flowchart LR
  A[frontmatter] --> B[标题与摘要]
  A --> C[分类与标签]
  A --> D[草稿与私密边界]
  A --> E[精选与阅读时间]
  B --> F[文章卡片]
  C --> G[分类 / 标签页]
  D --> H[公开页面过滤]
  E --> I[首页展示]

页面不手工维护链接,而是从文章字段生成列表、详情、分类和标签。

公开边界 draft

draft: true 不进入公开页面。

隐藏边界 private

private: true 不生成公开入口。

精选入口 featured

featured: true 可进入首页精选。

固定分类现在有四个:生活实践教程视觉实验室。分类负责内容类型,标签负责细粒度索引。

写作

写作流程尽量短:先选主题和分类,再写 frontmatter,最后用 Markdown / MDX 组织正文。

写作判断

Format 先选格式

普通笔记用 Markdown;需要卡片、图表或高亮说明时用 MDX。

Shape 再定结构

技术文章优先写成视觉笔记:结论、指标、流程、模块、检查清单。

Boundary 最后看发布边界

新文章默认 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。

Local

本地验证

用测试和构建确认内容边界、页面结构和 MDX 语法没有破坏站点。

  • npm test
  • npm run build
Pages

静态托管

线上托管的是构建后的 dist 文件,不需要 Node 服务、数据库或后台进程。

  • 访问地址:/
  • 发布来源:GitHub Actions

Agent 角色

Agent 不是发布系统本身,而是写作和维护流程里的协作者。它适合做结构整理、规则检查、图表补全和构建验证。

Draft

写作助手

把草稿整理成视觉笔记,补齐标题、摘要、卡片和流程图。

Review

规则审查

检查分类、草稿状态、敏感信息、frontmatter 和发布边界。

Verify

构建验证

运行项目已有命令,确认文章能被 Astro 正常构建。

静态取舍

这个博客没有数据库、登录、评论和后台权限。它牺牲的是在线编辑便利性,换来的是低维护成本、可版本化内容和稳定访问。

当前选择

静态博客

适合个人写作、版本管理、低成本部署和长期维护。

  • 复杂度主要在构建期
  • 线上访问链路短
  • 内容变更有 Git 记录
暂不需要

动态博客

适合多人后台、权限系统、评论互动和复杂查询。

  • 需要维护运行时服务
  • 需要数据库和权限模型
  • 当前阶段收益不够高

后续

后续演进会围绕写作体验和阅读体验逐步做,而不是一开始就扩成庞大系统。

演进顺序

Content 先沉淀内容

保持分类稳定,继续把生活、实践、教程和视觉实验室文章写下去。

Experience 再优化阅读

根据真实文章数量优化搜索、相关文章、系列文章和移动端阅读体验。

Build 最后补检查

需要时再加入链接检查、图片资源检查和更细的 frontmatter 校验。

小结