---
title: 一篇 mdx 的旅程
desc: frontmatter 元数据、路由总线与 PostLayout——单文件内容单元的完整管线。
date: "2026-10-31"
order: 1
tags: [MDX]
---

## 从落笔到页面

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

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

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

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

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