03 内容模型(二):从 Markdown 到 API
03 内容模型(二):从 Markdown 到 API
一句话结论:内容管线的核心不是解析 Markdown,而是决定哪些内容可以出现、以什么顺序出现、图片从哪里来;这些规则要写在代码里,不是写在文档里。
它解决什么问题
上一篇定好了 content/ 的目录、slug 和 frontmatter 契约。但文件不会自己变成站点,中间还差一层运行时:
- 哪些笔记可以发布,哪些还是草稿;
- 最新笔记按什么顺序排,系列内的顺序要不要反过来;
- 标签和系列怎么聚合,计数从哪里来;
- Markdown 怎么渲染,正文里的图片路径怎么处理;
- 文章不存在时返回什么,图片被猜到路径时会不会泄露文件。
这些问题看起来零碎,但每一个都可能让内容出错:草稿被 API 带出去、同一日期的笔记顺序每次不一样、系列里的文章倒着排、图片路径能跳出笔记目录。它们不会在 TypeScript 编译时报错,只会在上线后以很隐蔽的方式出现。
所以我把内容管线当成一个独立模块来做:server/utils/content.ts 负责读取、校验、过滤和聚合,Nitro 路由只负责把结果包成 JSON。规则写在函数里,测试覆盖边界,而不是靠「我记得要过滤草稿」。
我怎么试的
1. 两个加载函数,把「校验」和「发布」分开
export const loadAllNotes = (options: LoadContentOptions): ContentNote[] => {
// 读取全部笔记,包含草稿;任何校验错误都会抛 ContentValidationError
}
export const loadNotes = (options: LoadContentOptions): ContentNote[] => {
const notes = loadAllNotes(options)
if (options.includeDrafts) return notes
return notes.filter((note) => !note.draft)
}
loadAllNotes 给校验脚本用,草稿也要检查;loadNotes 给公开接口用,默认剔除 draft: true。两个函数分开,是为了避免「预览时想看草稿」和「发布时不能带草稿」互相打架。
摘要对象会再把 body 和 draft 去掉:
export const toNoteSummary = (note: ContentNote): NoteSummary => ({
slug: note.slug,
title: note.title,
summary: note.summary,
type: note.type,
date: note.date,
tags: note.tags,
series: note.series,
repo: note.repo,
website: note.website,
})
列表页不需要正文,也不应该知道草稿字段。少传一点,少一点泄露面。
2. 排序:日期倒序,slug 兜底
const byDateDescending = (first: ContentNote, second: ContentNote): number => {
if (first.date !== second.date) return first.date < second.date ? 1 : -1
return first.slug.localeCompare(second.slug)
}
日期是 YYYY-MM-DD 字符串,可以直接做字典序比较;同一天再用 slug 兜底,保证每次构建的顺序一致。没有这个兜底,同一天的两篇笔记可能因为文件系统返回顺序不同而换位置,RSS 和分页都会跟着抖。
系列内则是升序:
notes: groupedNotes.sort((first, second) => {
if (first.date !== second.date) return first.date < second.date ? -1 : 1
return first.slug.localeCompare(second.slug)
})
最新笔记要倒序,构建日志要正序,两个场景不该共用一个排序函数。
3. 标签和系列:从摘要聚合,不从正文猜
export const aggregateTags = (notes: NoteSummary[]): TagAggregate[] => {
const counts = new Map<string, number>()
for (const note of notes) {
for (const tag of note.tags) {
counts.set(tag, (counts.get(tag) ?? 0) + 1)
}
}
return [...counts.entries()]
.map(([name, count]) => ({ name, count }))
.sort(
(first, second) =>
second.count - first.count || first.name.localeCompare(second.name, 'zh-CN'),
)
}
标签按出现次数降序,次数相同按名称排序。系列则按文件夹名分组,系列之间按文件夹名升序(01- → 06-),组内按阅读序号升序,00-目录.md 因此排在系列第一位。两者都只吃 NoteSummary,不碰正文,所以草稿一旦被过滤掉,聚合结果里也不会出现它的标签和系列。
4. 两条 API:列表和详情
列表接口一次返回三样东西:
export default defineEventHandler(() => {
const contentDir = String(useRuntimeConfig().contentDir)
const notes = loadNotes({ contentDir })
const summaries = notes.map(toNoteSummary)
return {
notes: summaries,
tags: aggregateTags(summaries),
series: aggregateSeries(summaries),
}
})
详情接口按 slug 找笔记,找不到就 404:
const note = loadNotes({ contentDir: String(useRuntimeConfig().contentDir) }).find(
(item) => item.slug === slug,
)
if (!note) throw createError({ statusCode: 404, statusMessage: '笔记不存在' })
const { html, headings } = renderMarkdown(note)
return {
note: {
...toNoteSummary(note),
html,
headings,
},
}
这里有一个容易犯的错:详情接口也必须用 loadNotes,不能用 loadAllNotes。否则只要知道草稿的 slug,就能直接读到未发布内容。草稿过滤不是列表页的装饰,是接口层的边界。
renderMarkdown() 返回 HTML 和标题锚点两个值。锚点来自正文里的二、三级标题,文章页右侧的「本文目录」直接用它;渲染器只负责生成可跳转的 id,不加工作者写的章节序号。
5. 图片:改写路径,而不是相信路径
正文里的相对图片路径会被改写成站点地址:
return `/content-assets/notes/${slug}/${normalized
.split('/')
.map((segment) => encodeURIComponent(segment))
.join('/')}`
改写前会拒绝 ..、反斜杠和空路径,避免 ../../../etc/passwd 这类输入;外部 URL 和以 / 开头的站点绝对路径则原样保留。真正的文件读取在 content-assets 路由里,还要再过三道检查:
if (assetPath !== noteDir && !assetPath.startsWith(noteDir + sep)) throw notFound()
if (!existsSync(assetPath) || !statSync(assetPath).isFile()) throw notFound()
if (!CONTENT_TYPES[extname(assetPath).toLowerCase()]) throw notFound()
第一道防目录穿越,第二道确认文件存在,第三道只允许图片扩展名。路由还会先检查 slug 是否属于已发布笔记,所以草稿目录里的图片也不会被直接访问。
响应头也分环境:
setHeader(
event,
'Cache-Control',
import.meta.dev ? 'no-cache' : 'public, max-age=31536000, immutable',
)
生产环境把图片当成长期缓存资源,缓存一年。代价是:如果同一路径的图片被替换,浏览器和 CDN 不会自动失效。后面要么给文件名加 hash,要么接受「换图就换文件名」。
6. Markdown 渲染:默认不相信 HTML
const markdown = new MarkdownIt({
html: false,
linkify: true,
})
html: false 意味着正文里的原始 HTML 不会被渲染;linkify: true 让裸 URL 自动变成链接。图片渲染器会补上 loading="lazy" 和 decoding="async",避免长文里的图片阻塞首屏。
7. 用测试把边界固定下来
内容相关的测试目前有 27 个,覆盖加载、校验、草稿过滤、标签与系列聚合、构建脚本退出码、图片路径改写和目录穿越:
$ npx vitest run tests/nuxt/content.spec.ts
Test Files 1 passed (1)
Tests 27 passed (27)
全量测试是 110 个,全部通过。测试用临时目录造内容,不依赖仓库里真实的 content/notes/;这样即使内容目录是空的,管线本身也是被验证过的。
坑和限制
1. 草稿泄露只需要一次手滑。 公开接口误用 loadAllNotes,草稿就会出现在列表或详情里。测试里专门有一条断言「默认排除草稿」,但代码审查时仍然要盯住这个函数名。
2. 排序的稳定性靠约定。 日期相同必须用 slug 兜底,否则顺序会随文件系统变化。这个规则不写下来,下一个人(或者三个月后的我)很容易漏掉。
3. 标签没有规范化。 AI、ai、人工智能 现在是三个标签。聚合函数只负责计数,不负责合并同义词;等内容多起来,需要加白名单或归一化规则。
4. 图片缓存是「永久」的。 immutable 的前提是路径不变、内容不变。如果以后支持在后台替换封面图,就要加文件名 hash 或版本号,否则用户会一直看到旧图。
5. Markdown 的 HTML 是关掉的。 这挡住了 XSS,也挡住了 iframe、自定义组件和复杂嵌入。需要时应该加受控的 shortcode,而不是直接放开 html: true。
6. 内容目录必须进镜像。 前端运行时直接读 content/,部署时它必须被复制进镜像或挂载进容器;默认路径是仓库根 content/,可以用 NUXT_CONTENT_DIR 覆盖。这一点在写 Dockerfile 时还要再验证一次。
7. RSS 和 sitemap 还没接。 数据层已经保证草稿不会进入聚合结果,但 RSS、sitemap 和页面还没实现,所以「草稿不出现在生产」目前只在单元测试层面成立,等页面接上还要再验一遍。
8. 真实内容是空的。 写这一篇时 content/notes/ 还是空的,测试用的是临时目录。管线先于内容是我刻意选的顺序,但真正的考验是第一批 6-8 篇笔记写进来之后,schema 和写作流程会不会互相打架。现在笔记已经有 8 篇,这一关算是过了第一轮。
适合谁
如果你也在做一个 Git 驱动的内容站,想让内容和代码同仓库,又不想引入数据库,这套管线可以直接借鉴:一个 loader、一层 Zod 校验、两条 API、一个受控的图片路由,够用到内容规模很大之前。
如果你以后打算在同一份内容上做 RAG 或站内搜索,这层结构也有用:loadNotes 输出的就是干净的、已过滤的摘要和正文,Agent 不需要再理解你的目录约定。
它不太适合这几类人:用 CMS 或托管博客的人,这些能力平台已经给了;作者不是开发者、需要可视化编辑的团队;以及内容规模大到需要全文索引、权限和审核流的场景。
下一篇写 04 前端:Nuxt + SCSS 的页面实现。内容管线已经把数据准备好了,接下来要把它变成首页、目录、详情和关于四个页面,并在 1440 / 1024 / 768 / 390 四个宽度上验证。