---
title: 编写 MDX 内容
description: 如何编写语义编译器能提取含义的 MDX 文件。
canonical_url: https://next-ai-ready.vercel.app/zh/docs/guides/mdx-content
url: https://next-ai-ready.vercel.app/zh/docs/guides/mdx-content
last_updated: 2026-06-02
updated: 2026-06-02
author: next-ai-ready 团队
summary: 如何编写语义编译器能提取含义的 MDX 文件。
topics: [how-to, best-practices]
---

# 编写 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
---
```

| 字段           | 类型       | 必填 | 说明                                         |
| ------------ | -------- | -- | ------------------------------------------ |
| `title`      | string   | 是  | 页面标题。用于 `llms.txt`、JSON-LD 和 `<title>` 标签。 |
| `summary`    | string   | 推荐 | 一句话描述。用于搜索结果和 AI 摘要。                       |
| `updatedAt`  | ISO date | 否  | 发布日期。向 AI 消费者传递新鲜度信号。                      |
| `author`     | object   | 否  | `{ name, url? }`。用于 JSON-LD 的 `author` 字段。 |
| `reviewedBy` | object   | 否  | `{ 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" },
  ],
}
```

| 字段          | 类型                       | 说明                            |
| ----------- | ------------------------ | ----------------------------- |
| `topics`    | `string[]`               | 关键词，用于搜索和分类。                  |
| `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 调用。