MDX网页使用技巧

目标

这篇 quickstart 说明怎么把 src/mdx 里的内容源接成网页

最常见的流程是:

1. 在 src/mdx 下新增一个顶层目录, 例如 arch
2. 在 site-docs-base.ts 里允许这个 sourceKey
3. 新增一个页面入口, 调用 siteDocs.getContentSource('arch')
4. 在 site-docs.ts 控制这个 MDX 源启用哪些能力

内容源目录

local-md 默认把 sourceKey 映射到同名目录:

不改 dir 时, 目录名和 sourceKey 保持一致即可

开放 sourceKey

新增内容源时, 先改 SourceKey这里是应用层限制, 不是底层包限制

SourceFactory 只是工厂返回值的类型别名, 主要用于给 getCachedSource 的 overrides 参数补类型

调用时直接传目录同名 key:

page.data 结构

createFumaPage() 最终拿到的是 source.getPage(slug, locale) 返回的 page。业务最常直接读的是 page.data。

固定字段

这些字段是当前流程里稳定可用的:

可透传字段

frontmatter 里写的其他字段也会进入 page.data, 前提是字段名不和上面的固定字段冲突.

例如:

业务侧可以直接读取:

build 和 runtime 的一致性

build 和 runtime 都会保留这些字段:

• page.frontmatter 先被解析出来
• 然后透传到 page.data
• 再补上 body, load, toc, structuredData 这些渲染期字段

所以从业务方视角看, page.data 就是页面元数据, 自定义 frontmatter, 渲染结果的集合.

资源首页和聚合页

如果要做资源首页、专题页、列表页, 不需要改 createFumaPage()。业务方自己写一个聚合函数就行.

数据来源

推荐流程:

1. siteDocs.getContentSource(sourceKey) 拿到 source
2. source.generateParams('slug', 'locale') 拿到所有页面位置
3. source.getPage(slug, locale) 拿到每篇 MDX 的 page.data
4. 业务方把 page.data 组装成首页卡片数据
5. 点击卡片跳转到对应 MDX 页面

slug 从哪里来

slug 不是猜出来的, 也不是从 page.path 直接反推出来的。它来自 source 自己的路由生成结果:

params 里的每一项都有 slug 和 locale, 业务方直接拿来做列表渲染就行。

href 怎么拼

底层 ZiaCard 也是直接接收 href, 例如:

业务方首页可以自己拼同样的链接:

如果没有 locale 前缀, 就按现有路由规则去掉即可:

首页和详情页怎么拆

像 blog 这种资源, 最稳的方式是拆成两条路由:

• 首页: (home)/blog/page.tsx
• 详情页: (content)/blog/[...slug]/page.tsx

首页本身也是 blog 路径, 只是它在 home 分组里渲染聚合页. 详情页继续交给 createFumaPage(), 并放在 SiteDocsLayout 里.

首页里只需要做一件事:

然后把每个 slug 组装成卡片链接:

如果你挂在 locale 路径下, 就用现成的 locale 拼接工具, 但资源路径还是跟 sourceKey 走.

业务方可直接用的字段

首页聚合页可以直接用:

• page.data.title
• page.data.description
• page.data.icon
• page.data.date
• page.data 里的自定义 frontmatter 字段

这样资源首页既能展示 MDX 的主要信息, 也能直接跳转到对应的 MDX 页面.

例如博客可以额外使用 author 和 tags:

聚合函数读取这些字段:

页面入口

页面入口负责把某个 sourceKey 接到路由上下面是典型写法, 照着 blog 页面改 sourceKey 即可

关键参数:

如果你新增了 arch, appConfig.mdxSourceDir 也要能取到它:

包级能力开关

site-docs.ts 是当前应用统一的 MDX 能力开关这里控制整套 MDX 页面能用哪些扩展能力

开关含义:

如果某类页面不需要全部能力, 可以新增一个单独的 createSiteDocs 配置, 再让页面入口引用它

页面入口使用对应实例:

构建和运行

新增或修改 src/mdx 内容源后, 先生成 .source:

开发时默认也建议走 .source, 这样和生产环境一致

如果只是在本地快速写文档, 可以临时启用 runtime:

发布前使用:

Vercel 文件路径

部署到 Vercel 时, Serverless Function 不一定会自动带上 src/mdx 和 .source如果线上页面或 llm-content API 读不到文件, 需要在 next.config.ts 顶层配置 outputFileTracingIncludes

规则很简单:

线上成功配置示例:

如果新增 arch, 就按同样模式补:

注意 outputFileTracingIncludes 必须是 nextConfig 的顶层属性, 不要放进 experimental、images 或其他子配置里

最小检查清单