/docs站（你正在看的这个，docs.vibestrap.dev）跑在 Mintlify 上， 内容在仓库根的docs/和docs/docs.json。接入指南： 部署 docs 到 Mintlify。- 营销应用上的
/blog和/changelog跑在 Fumadocs 上，MDX 在content/blog/和content/changelog/。本篇说的就是这两个。
集合是如何定义的
source.config.ts：
dir 与 Zod schema。构建时会生成 .source/server.ts，
导出类型化的数组，由 src/lib/source.ts 消费。
新增一篇博客
Blog 的 frontmatter 字段最多：content/blog/<slug>.mdx 加上 <slug>.zh.mdx。
博客索引页用 pickByLocale(blog, locale) 读取，按 date 倒序——无需额外配置。
新增一条 changelog
跟 blog 一样的结构，多一个必填的version：
content/changelog/。version 字段决定标题展示和 /changelog 上的排序。
pages 集合
content/pages/ 是杂项 MDX 页面的家——不属于 blog 或 changelog 的内容。
当前只有占位符。需要 MDX 渲染但不要侧边栏导航时用它。
自定义 MDX 组件
src/mdx-components.tsx 是 blog + changelog 渲染的统一覆盖点。它把样式
交给 Tailwind 的 prose 插件。在这里加自定义 shortcode：
<Callout>...</Callout> 了。
（Mintlify docs 站有它自己的组件库——见
Mintlify Components。）
验证生效
pnpm build 会自动跑 fumadocs-mdx——frontmatter 不合规则时会以 Zod 错误
失败、明确指出文件。
常见坑
- 忘记重新生成
.source/——加文件后 dev 里 404，跑一下pnpm exec fumadocs-mdx。 - frontmatter 不合法——Zod 拒绝未知字段。
date必须能解析、 changelog 必须有version、published: false会隐藏博客。 - MDX autolink——写
<https://example.com>会让 MDX 解析炸。 用[example.com](https://example.com)或裸 URL。 - 目录搞错——配置目录之外的文件会被静默忽略，对照
source.config.ts。 - 不要把 docs 放这里——任何想出现在
/docs上的内容都属于仓库根的docs/（Mintlify），不是content/docs/。
官方文档
- fumadocs.vercel.app —— Fumadocs 参考
- Fumadocs MDX —— 集合配置
- MDX —— Markdown + JSX 语法
- Zod —— frontmatter schema 语法