​
目录结构

每篇文章一个目录： 
content/blog/
  my-post-slug/
    index.mdx
    assets/

​
Frontmatter 字段

lib/blog/frontmatter.ts 会校验以下字段： 
---
title: "AI for Materials: First Principles"
summary: "A foundation for electrochemical modeling workflows."
status: "published" # draft | published | archived
publishedAt: "2025-03-12"
series: "energy-materials-lab"
tags: "ai,electrochemistry"
cover: "/img/test.png"
readingMinutes: 10
featured: false
---

​
标签与系列规则

  • tags 是逗号字符串
  • 同步时会执行：trim + lower + 去重
  • series 和 tags 会转换为 slug（拼音化）
  • 一篇 Blog 最多一个系列，可有多个标签

​
封面图规则

支持的常见写法：
  • 绝对 URL：https://...
  • 公共路径：/img/...、/uploads/...
  • 内容相对路径：./assets/cover.png
在相对路径场景中，渲染层会按文章 slug 拼接成可访问路径。

​
发布流程（推荐）

1

编辑或新增 MDX

在 content/blog/<slug>/index.mdx 完成正文和 frontmatter。
2

本地预演同步

执行 npm run content:sync:dry 检查是否可成功解析。
3

写入数据库

执行 npm run content:sync，让页面读取到最新内容。
4

验证页面

打开 /blog 和 /blog/<slug>，检查摘要、标签、系列与目录锚点。

​
归档行为

如果你删除了某个 content/blog/<slug> 目录，下次同步会把数据库中的同名文章状态标记为 ARCHIVED，而不是直接删除。

​
常见问题

​
问题：文章不显示在 /blog

检查项：
  1. status 是否是 published
  2. 是否执行了 npm run content:sync
  3. publishedAt 是否可被解析

​
问题：标签聚合页为空

检查 tags 是否为空字符串，或包含了无效字符导致 slug 为空。