一篇 mdx 的旅程

Sat, 31 Oct 2026 00:00:00 GMT

从落笔到页面

以 posts/hello.mdx 为例。这个文件从写完到能访问，中间发生三件事：

lib/atlas.js 用 import.meta.glob 读进所有 mdx 的 frontmatter，和目录的 atlas.json 合成一张登记表；
pages/[...slug].astro 按登记表生成路由——文件在 posts/hello.mdx，地址就是 /posts/hello/，产物是 dist/posts/hello/index.html；
渲染时包上 PostLayout：系列章节左栏挂目录树，题头带系列徽章、日期、标签；散篇不挂树，上一篇/下一篇按日期相邻。

frontmatter 长这样。有个小坑我踩过：日期要带引号，不然 YAML 会把它解析成 Date 对象，校验器直接报格式错误。

---
title: 文章标题
desc: 一句话摘要（列表与 RSS 用）
date: "2026-10-31"
tags: [检索词]
order: 1        # 系列章节必填；分组里与兄弟同级排序
draft: true     # 草稿：不产出、不进列表与 RSS
---

mdx 和纯 markdown 的区别就一条：正文里可以 import 组件。开篇那篇 hello 里的章节标题 SectionHead，就是正文里一行 import 拿来用的——写文章时能用上整套站点积木，这是当初选 mdx 而不是纯 markdown 的主要原因。

目录树侧栏与 RSS

Sat, 31 Oct 2026 00:00:00 GMT

左栏的树

这个系列左边的目录树不用手工维护，数据就是目录结构本身：

章节（mdx）是叶子链接；
section 分组是分组标题，可以嵌套——“框架机制""发布管线”就是两个分组；
同级按 frontmatter 的 order 混排，SeriesTree 组件递归渲染，当前页高亮。

桌面端侧栏 sticky 跟着滚动，移动端整棵树堆到正文上方。你现在在本页左侧看到的就是它。

prose 排版

mdx 渲染出来是裸 HTML，得有人管排版。global.css 里一套 .prose 样式接手：标题下加虚线，引用块左边一条印章红，代码块用 Shiki 的 vitesse-light 配色。文章页能和全站的纸面风格对上，靠的就是这一层。

订阅源

rss.xml 也是构建期的产物：src/pages/rss.xml.js 从登记表拿全部已发布文章，生成标题、摘要、日期、分类，draft 天然不进。

后来又补了一个构建后处理的小脚本：把每篇文章渲染出的

整块注进 content:encoded。原因是 Astro 7 的容器渲染不了 MDX 编译产物，只能在构建完成后从产出的 HTML 里取。效果是订阅器里能直接读全文，不用点回网页。

你好，世界

Sat, 31 Oct 2026 00:00:00 GMT

引言

这是第一篇。顺手把发布管线整个验收一遍。

小站开张。你现在看到的这页，就是这个 mdx 文件跑完 astro build 的产物。所以第一篇不讲道理，直接当验收单用——文中用到的每种排版能力，都是管线的一部分。

No.01

这不是普通的 Markdown

文件后缀是 .mdx：markdown 里可以直接用组件。上面那块带「No.01」的章节标题不是截图，是正文里一行 import 引入的 SectionHead 组件。

标题、列表、引用

标准 Markdown 全家桶都认：标题、列表、加粗、链接、行内代码
代码块带 Shiki 高亮：

// 路径即地址：内容目录树就是站点树
export const u = (p) => import.meta.env.BASE_URL + p;

引用块长这样：左边一条印章红，底色微微泛红。

元数据来源	载体	谁在用
目录	`atlas.json`	索引页 / 系列
单文件	frontmatter	每篇 mdx

图片直接住进文章

图片跟 mdx 放同一目录、相对路径引用，构建时自动走 astro:assets 优化，产出带哈希的 _astro/ 资产。content/ 里不用另建资产目录。

锚点与目录

每级标题都有了自己的 id（悬停可见 #），右侧的页内目录就是从这些 id 来的。长文回头翻某一段，不用滚来滚去。

就写到这儿。下一篇见。

三条规矩

Fri, 30 Oct 2026 00:00:00 GMT

三条规矩

给这个站立了三条规矩，多一条都嫌重：

路径决定 URL——目录层次就是地址层次，唯一的强约束；
元数据自述身份——目录的元数据写在 atlas.json 里，单文件的写在 frontmatter 里；
index.astro 是自由创作——页面读哪些数据、拼哪些积木，框架不管。

第一条管地址，第二条管数据，第三条管自由度。这个站后来所有机制，都是从这三句推出来的。

目录的四种角色

目录在 atlas.json 里自报一种 type，和实际结构互验，写错了构建直接报错：

type	结构条件	用途
`map`	有子目录或散篇 mdx	索引页（如 `/posts/`）
`series`	有 mdx 章节	文档树：落地页 + 目录树侧栏
`section`	住在系列树里且非空	分组节点：只当树用，不承载页面
`case`	叶子	内容本身（自由创作的页面）

系列支持嵌套：section 分组里还能再放 section，像 doc 站那样把章节归组成树。分组不需要 index.astro——建个目录、写份元数据（title + order）就上树。章节和分组的 order 在同一层里混排，上一篇/下一篇沿整棵树深度优先走下来，跨分组也是连续的。

构建期校验

Fri, 30 Oct 2026 00:00:00 GMT

两档校验

lib/validate.js 在每次 dev / build 都会跑一遍，分两档：

data 模式（恒开）：schema、角色和结构互验、markers 引用完整性、 mdx 地址与目录地址的撞车检测；
full 模式（设 ATLAS_FULL=0 可临时关）：登记表和页面文件互相对账。

它能拦住什么

举几个真实会报错的例子。同一目录下两个章节写了相同的 order，构建直接失败：

[atlas] ../content/posts/building-this-site/publishing/rss.mdx: order 2 与 ../content/posts/building-this-site/publishing/mdx.mdx 重复——同一目录内序号必须唯一

往目录里塞 index.mdx（目录索引只允许 index.astro 承载）：

[atlas] (index.mdx): ../content/posts/index.mdx 不允许——目录索引一律用 index.astro（写系列引言请在落地页 astro 里写）

还有散篇推导出的地址撞上目录、section 分组建在系列树之外、markers 引用了不存在的 id、散篇忘了写日期……全都一样：构建失败，错误信息带着文件路径，当场改当场好。

为什么这么严

静态站怕的不是报错，是错得没声音。章节顺序排错了、链接指空了，页面上一点动静都没有，等哪天自己翻到了才发现，那时候它已经在线上挂了不知多久。

构建期校验把这类事故拦在本地。报错烦人，但比悄悄坏掉强。

为什么自己搭

Thu, 29 Oct 2026 00:00:00 GMT

从旧站说起

旧博客（blog.gcbo.fun）是 2025 年年中搭的：Trilium 管内容，Next.js 负责呈现，中间靠 API 缝合。用着没什么大毛病，但它终究是个动态服务——要跑 Node、要管进程守护，Trilium 那头的笔记和页面之间也永远隔着一层转换逻辑。

这次想换个活法：内容就是文件，构建完就是 HTML，扔到任意静态托管上就完事。没有服务要挂，没有依赖要追，过几年回来打开还能用。

为什么选 Astro

选型时最后定了 Astro，理由很实际：

内容就是文件。一篇 .mdx 一篇文章，git 管着，任意编辑器能写；
默认零运行时，产物是纯 HTML，页面不背框架 JS；
页面怎么写，框架不管。这一点最合口味——下一篇会讲，我只给这个站立了三条规矩。

至于为什么不是 Hugo、Hexo 这类纯生成器：我想在文章里直接用组件，比如开篇那篇 hello 里的章节标题就是正文里 import 来的 SectionHead。mdx 的灵活度对我是刚需。为什么不是 Next.js SSG：旧站就是 Next.js，太自由了，自由到每个页面都可以有自己的写法，写到后面自己都记不住哪套是哪套。

只留一条规矩

新站只保留一条强约束：路径决定 URL。src/content/ 的目录树就是站点树，也是构建产物的镜像——文件放哪，地址就在哪。

其余全部自由。规矩少一点，写得下去的可能性就大一点。

b1babo

一篇 mdx 的旅程

从落笔到页面#

目录树侧栏与 RSS

左栏的树#

prose 排版#

订阅源#

你好，世界

这不是普通的 Markdown

标题、列表、引用#

图片直接住进文章#

锚点与目录#

三条规矩

三条规矩#

目录的四种角色#

构建期校验

两档校验#

它能拦住什么#

为什么这么严#

为什么自己搭

从旧站说起#

为什么选 Astro#

只留一条规矩#

从落笔到页面

左栏的树

prose 排版

订阅源

标题、列表、引用

图片直接住进文章

锚点与目录

三条规矩

目录的四种角色

两档校验

它能拦住什么

为什么这么严

从旧站说起

为什么选 Astro

只留一条规矩