跳转到主要内容
vibestrap 用了两套 MDX 系统，各司其职：
  • /docs 站（你正在看的这个，docs.vibestrap.dev）跑在 Mintlify 上， 内容在仓库根的 docs/ 和 docs/docs.json。接入指南： 部署 docs 到 Mintlify。
  • 营销应用上的 /blog 和 /changelog 跑在 Fumadocs 上，MDX 在 content/blog/ 和 content/changelog/。本篇说的就是这两个。
分开是有意为之：docs 用 Mintlify 拿到现成的导航 / 搜索 / AI 助手 / 多语言； blog 和 changelog 是营销站的一部分，跟 Next.js 应用同站更合理（共享主题、 共享分析、locale 路由统一）。

​
集合是如何定义的

source.config.ts： 
export const blog = defineCollections({
  type: 'doc',
  dir: 'content/blog',
  schema: frontmatterSchema.extend({ /* date, author, categories, … */ }),
});

export const changelog = defineCollections({
  type: 'doc',
  dir: 'content/changelog',
  schema: frontmatterSchema.extend({ version: z.string(), date: ... }),
});

export const pages = defineCollections({
  type: 'doc',
  dir: 'content/pages',
  schema: frontmatterSchema,
});
每条定义指定一个 dir 与 Zod schema。构建时会生成 .source/server.ts， 导出类型化的数组，由 src/lib/source.ts 消费。

​
新增一篇博客

Blog 的 frontmatter 字段最多： 
---
title: 欢迎来到 vibestrap
description: 一句话总结。
date: 2026-04-27
author: vibestrap
categories: [release, indie-hacking]
---
把文件丢到 content/blog/<slug>.mdx 加上 <slug>.zh.mdx。 博客索引页用 pickByLocale(blog, locale) 读取，按 date 倒序——无需额外配置。

​
新增一条 changelog

跟 blog 一样的结构，多一个必填的 version： 
---
title: v1.1 —— 积分包
description: 小但精。
version: 1.1.0
date: 2026-05-15
---
文件放到 content/changelog/。version 字段决定标题展示和 /changelog 上的排序。

​
pages 集合

content/pages/ 是杂项 MDX 页面的家——不属于 blog 或 changelog 的内容。 当前只有占位符。需要 MDX 渲染但不要侧边栏导航时用它。

​
自定义 MDX 组件

src/mdx-components.tsx 是 blog + changelog 渲染的统一覆盖点。它把样式 交给 Tailwind 的 prose 插件。在这里加自定义 shortcode： 
export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    Callout: ({ children }) => <div className="callout">{children}</div>,
    ...components,
  };
}
之后任意 blog / changelog MDX 文件里就能用 <Callout>...</Callout> 了。 （Mintlify docs 站有它自己的组件库——见 Mintlify Components。）

​
验证生效

pnpm exec fumadocs-mdx   # 重新生成 .source/
pnpm dev                 # 访问新文章
pnpm build               # frontmatter schema 错误会在这里暴露
pnpm build 会自动跑 fumadocs-mdx——frontmatter 不合规则时会以 Zod 错误 失败、明确指出文件。

​
常见坑

  1. 忘记重新生成 .source/——加文件后 dev 里 404，跑一下 pnpm exec fumadocs-mdx。
  2. frontmatter 不合法——Zod 拒绝未知字段。date 必须能解析、 changelog 必须有 version、published: false 会隐藏博客。
  3. MDX autolink——写 <https://example.com> 会让 MDX 解析炸。 用 [example.com](https://example.com) 或裸 URL。
  4. 目录搞错——配置目录之外的文件会被静默忽略，对照 source.config.ts。
  5. 不要把 docs 放这里——任何想出现在 /docs 上的内容都属于仓库根的 docs/（Mintlify），不是 content/docs/。

​
官方文档