next/ai-ready
EN

guides

编写 MDX 内容

如何编写语义编译器能提取含义的 MDX 文件。

知识平面读取你的 MDX 文件并提取结构化元数据。本指南介绍如何编写产出最佳结果的内容。

说明（docs-site）： 本站采用双轨架构。浏览器 UI 通过 MdxContent 渲染简化 Markdown；AI 构建管线使用完整的 @next-ai-ready/mdx 编译器。请为 AI 轨编写 frontmatter（summary、questions、tags），即使 UI 轨不执行 MDX export。

文件位置

将 MDX 文件放在 ai-ready.config.mjs 中 content glob 匹配的目录下。默认 glob 为：

js
content: ["app/**/*.{md,mdx}", "content/**/*.mdx"]

文件路径决定路由。例如，content/docs/getting-started.mdx 映射到 /docs/getting-started。

Frontmatter

每个 MDX 文件应有至少包含 title 的 YAML frontmatter：

yaml
---
title: 快速开始
summary: 60 秒内安装并运行。
updatedAt: 2026-05-28
author:
  name: Jair
  url: https://github.com/jair
---
字段类型必填说明
titlestring是页面标题。用于 llms.txt、JSON-LD 和 <title> 标签。
summarystring推荐一句话描述。用于搜索结果和 AI 摘要。
updatedAtISO date否发布日期。向 AI 消费者传递新鲜度信号。
authorobject否{ name, url? }。用于 JSON-LD 的 author 字段。
reviewedByobject否{ name, url? }。AI 搜索的 E-E-A-T 信号。

语义元数据导出

为了更丰富的提取，可以从 MDX 导出 semantic 对象：

ts
export const semantic = {
  topics: ["install", "quickstart", "pnpm"],
  questions: [
    { q: "如何安装 next-ai-ready？", a: "运行 `pnpm add next-ai-ready`。" },
    { q: "需要 Zod 吗？", a: "是的，action 需要 Zod v4。" },
  ],
  entities: [
    { name: "pnpm", type: "tool", url: "https://pnpm.io" },
  ],
}
字段类型说明
topicsstring[]关键词，用于搜索和分类。
questions{ q, a }[]FAQ 条目。提取为 FAQPage JSON-LD。
entities{ name, type, url? }[]命名实体（人物、工具、公司）。

标题

使用 ## 标题将页面分成多个章节。每个标题成为一个独立的 SemanticNode(kind="section")，带有自己的锚点 URL：

text
## 安装

运行 `pnpm add next-ai-ready`。

## 配置

编辑 `ai-ready.config.mjs`...

编译器保留标题 ID 以确保锚点链接稳定。AI 消费者可以通过 citeUrl 引用特定章节。

代码块

使用带语言标签的围栏代码块。用三个反引号加语言标识符包裹代码：

`bash

pnpm add next-ai-ready

`

编译器在 Markdown body 中将代码块剥离为纯文本，但在 HTML 输出中保留。

支持的标签：bash、ts、js、json、text（以及语法高亮器识别的其他标签）。

提取结果

从每个 MDX 文件，编译器产出：

  • 标题 — 来自 frontmatter title 或第一个 # 标题。
  • 摘要 — 来自 frontmatter summary 或第一段。
  • 章节 — 每个 ## 标题一个，包含正文。
  • FAQ — 来自 semantic.questions 导出。
  • 实体 — 来自 semantic.entities 导出。
  • 分块 — 感知 token 的分割，尊重标题边界。
  • JSON-LD — WebPage、Article、FAQPage 和 BreadcrumbList 块。

所有提取都是确定性的，无 LLM 调用。