写作文档

这篇文档合并说明 Clarify 中和“写内容”有关的核心能力：MDX、Frontmatter、文件路由、OpenAPI 文件路由、代码块和内置组件。

目标是让作者知道：文件应该放在哪里、页面如何生成、元数据怎么写、什么时候使用组件。

推荐目录结构

把文档按读者任务组织，而不是按内部模块组织：

source/
├── index.mdx
├── getting-started.mdx
├── guides/
│   ├── writing.mdx
│   └── deploy.mdx
├── reference/
│   └── config.mdx
└── api.openapi.json

启用国际化时，把同样的结构放进 locale 目录：

source/
├── zh-CN/
│   ├── index.mdx
│   └── getting-started.mdx
└── en-US/
    ├── index.mdx
    └── getting-started.mdx

文件就是路由

Clarify 按照 source/ 下的文件结构生成页面路径：

规则：

• index.mdx 映射为所在目录根路径。
• 文件名建议使用小写和连字符，例如 api-authentication.mdx。
• 支持 .mdx 内容文件，以及 .openapi.json、.openapi.yaml、.openapi.yml 规范文件。
• 如果站点部署在子路径，使用 routePrefix 配置前缀，见 配置站点。

MDX 基础

Clarify 使用 MDX，你可以写普通 Markdown，也可以嵌入 JSX。

# 标题

**粗体**、*斜体*、`行内代码`。

- 列表项 1
- 列表项 2

> 引用块

嵌入 JSX：

# 欢迎使用

<div className="rounded-lg border p-4">
  这是一个 React 片段。
</div>

导入自定义组件：

import { Alert } from '../components/Alert'

# 页面标题

<Alert type="warning">
  这是一条警告信息。
</Alert>

Frontmatter

每个页面顶部可以添加 YAML frontmatter，用于页面标题和描述：

---
title: 页面标题
description: 页面描述，用于 SEO 和社交分享
---

# 正文内容

当前稳定字段：

当前版本不提供 navOrder、hidden 等高级 frontmatter 字段。要控制侧边栏，请在 clarify.ts 中显式配置 tabs。

标题、目录与搜索

Clarify 会从内容中提取 H2/H3 作为页面章节。章节会用于页面内导航和站内搜索，因此标题不是纯排版元素，也是信息架构的一部分。

# API 文档

## 认证

### 创建访问令牌

## 分页

建议：

• H1 表达页面主题；如果 frontmatter 没有 title，Clarify 会尝试用 H1 作为页面标题。
• H2 表达用户任务或主要问题，例如“创建访问令牌”“部署到 GitHub Pages”。
• H3 表达任务中的子步骤或细分场景。
• 避免大量使用“介绍”“更多”“其他”这类弱标题。

内置搜索会检索页面标题、导航分组、路径和 H2/H3 章节标题，并返回最相关的少量结果。它适合帮助用户快速跳到页面或章节；如果你需要全文搜索索引，可以通过插件在构建阶段生成额外产物。

代码块与 GFM

代码块会自动高亮。建议始终标注语言名，这样可以获得更准确的语法高亮和复制体验：

function greet(name: string): string {
  return `Hello, ${name}!`
}

如果语言名无法识别，Clarify 会回退为普通代码块渲染，不会阻塞页面构建。

内置 GitHub Flavored Markdown 支持：

- [x] 支持表格
- [x] 支持任务列表
- [ ] 支持更多写作体验

内置组件

Clarify 在 MDX 中默认注册了一组公开组件，无需手动导入即可直接使用：

• Callout、Note
• CardGroup / Card
• Button
• CodeGroup
• Collapse
• Row / Col
• Properties / Property
• Markdown
• OpenApiOperation
• OpenApiDocument

示例：

<Callout type="tip" title="建议">
  把用户任务放在导航前面，把字段参考放在后面。
</Callout>

<CardGroup cols={2}>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    安装 CLI 并创建第一个文档站点。
  </Card>
  <Card title="API 文档" icon="braces" href="/features/openapi">
    从 OpenAPI 生成 Reference 并嵌入接口。
  </Card>
</CardGroup>

完整属性请参考 内置公开组件。

如果你需要项目专属组件，可以通过 MDX import 导入本地 React 组件：

import { Alert } from '../components/Alert'

写作建议

• 一篇文档解决一个用户任务，不要为每个内部能力单独开文档。
• 先讲为什么，再讲怎么做，让读者知道当前步骤的价值。
• 把字段列表放进参考页，任务页只保留最常用配置。
• 用清晰的 H2/H3 承载搜索入口，让用户能从搜索结果直接跳到具体章节。
• 多用表格和短代码示例，减少长段落。
• 让 OpenAPI 承担接口事实来源，教程只解释业务流程。
• 把内容写成 AI 也能消费的结构：标题清晰、步骤明确、示例完整，构建后的 .md 和 llms.txt 会保留这些结构。