​

项目配置 - API易文档中心

​

项目概述

​

文档编写规范

​

MDX文件格式要求

• 重要：Mintlify会自动从frontmatter的title字段生成H1标题
• 禁止：在MDX文件内容中使用H1标题（# 标题）
• 原因：会导致页面出现重复的H1标题，影响SEO和用户体验

​

正确的文件结构

---
title: "页面标题"
description: "页面描述"
icon: "图标名称"
---

## 第一个章节标题
内容从H2开始...

### 子标题
使用H3及以下级别的标题

​

错误的文件结构（避免）

---
title: "页面标题"
---

# 页面标题  ← 不要这样做！会重复显示

## 第一个章节标题

​

文档系统说明

• 使用Mintlify文档框架
• 支持MDX格式（Markdown + JSX组件）
• 导航结构在docs.json中定义
• 图片资源存放在images/目录

​

FAQ页面组织

• 所有FAQ页面位于faq/目录
• 作为独立的顶级标签页展示
• 每个问题一个独立的MDX文件

​

编写新内容时的注意事项

1. 遵循上述MDX格式规范
2. 使用适当的Mintlify组件（Info, Warning, Tip, Card等）
3. 保持中文内容的专业性和友好性
4. 引用图片时使用相对路径/images/文件名
5. 时间必须标注时区：文档中涉及具体时间时，必须附加时区说明（如 18:30 (UTC+8)），因为我们有全球客户
   • ✅ 正确：18:30 (UTC+8)、6:30 PM (UTC+8)
   • ❌ 错误：18:30、今晚六点半（缺少时区，全球客户无法判断）
6. 英文内容品牌名用 APIYI：英文页面（en/ 目录）中品牌名一律写 APIYI，不要写 API易；中文页面仍用 API易
   • ✅ 正确（英文）：the APIYI gateway、paste your APIYI key
   • ❌ 错误（英文）：the API易 gateway
   • 域名、代码示例不受影响：api.apiyi.com、APIYI_API_KEY 等保持原样
7. 新建页面必须中英双语同步：每次创建一个新页面时，必须同时产出中文版（根目录）和英文版（en/ 目录），两份内容对应、文件名一致，并在 docs.json 的中文版和英文版导航中同时注册（位置一致）。不允许只建一个语言版本。
   • 中文页内部链接用 /api-capabilities/...，英文页内部链接用 /en/api-capabilities/...
   • 英文版品牌名遵循第 6 条（APIYI）
8. 页面标题不要中英混排：title / sidebarTitle 只用单一语言。中文页只写中文（如 原生工具出图），英文页只写英文（如 Native Tool Image Generation），不要写成 原生工具出图（Responses image_generation） 这种括号混排。

​

大模型百科写作规范

​

词条页面结构

---
title: "词条名称"
description: "简短描述(1-2句话，80字以内)"
icon: "相关图标"
tags: ["标签1", "标签2", "标签3"]
difficulty: "basic|intermediate|advanced"
related: ["相关词条1", "相关词条2"]
---

## 概念定义
[30-50字的核心定义，适合小白理解]

## 详细解释 
[200-400字的详细说明，专业但易懂]

## 工作原理
[配图解说明，解释核心机制]

## 实际应用
[具体应用场景和案例]

## 相关概念
[链接到其他相关词条]

## 延伸阅读
[权威参考资源]

​

写作风格指南

• 专业性：确保技术准确性，引用权威来源
• 易懂性：用类比和实例帮助理解复杂概念
• 简洁性：避免冗长，重点突出
• 交互性：善用图解说明和交叉引用
• 更新性：及时反映最新技术发展

​

联网搜索要求

• 必须联网：创建每个词条前必须进行联网搜索
• 信息时效：确保引用最新的技术发展、模型更新、研究成果
• 多源验证：交叉验证多个权威来源的信息
• 版本更新：特别注意模型版本、API更新、性能指标等时效性信息
• 标注日期：对于快速变化的信息，标注数据获取时间

​

难度分级标准

• basic：面向初学者，无需预备知识
• intermediate：需要基础概念理解
• advanced：需要深度技术背景

​

图片格式要求

​

推荐格式

• PNG：用于图解、流程图、架构图等需要高质量显示的图片
• JPEG：用于照片类图像，文件较大但压缩率高
• 外部托管SVG：如需使用SVG，建议外部托管并通过URL引用

​

格式使用指南

• 图解说明：优先使用PNG格式，确保清晰度和兼容性
• 图标：使用Font Awesome或Lucide内置图标，避免自定义SVG
• 浅色/深色主题：为不同主题准备两个版本的PNG图片
  <img className="block dark:hidden" src="/images/diagram-light.png" alt="浅色主题图解" />
  <img className="hidden dark:block" src="/images/diagram-dark.png" alt="深色主题图解" />
  

​

注意事项

• 避免内联SVG：Mintlify对内联SVG支持存在问题，可能导致渲染错误
• 文件大小：PNG文件控制在200KB以内，JPEG控制在500KB以内
• 命名规范：使用描述性文件名，如 transformer-architecture-light.png
• 测试环境：本地预览正常不代表生产环境正常，务必在部署后检查

​

其他要求

• 注意：不使用 HTML 注释语法，需要使用JSX注释语法
• 价格符号转义：$ 符号的处理方式取决于所在语境，正文和 frontmatter 规则相反，不要混用
  • MDX 正文（含表格）：必须转义为 \$，避免被 LaTeX 数学模式吞掉
    • ✅ 正确：\$2.00 / 百万 tokens
    • ❌ 错误：$2.00 / 百万 tokens（会触发 LaTeX 解析错误）
  • Frontmatter（YAML）：直接写 $，不要转义
    • ✅ 正确：description: "价格 $0.42/$2.52 每 1M tokens"
    • ❌ 错误：description: "价格 \$0.42/\$2.52 每 1M tokens"
    • 原因：YAML 双引号字符串里 \$ 不是合法转义序列（YAML 只认 \n \t \" \\ 等），会触发 frontmatter 解析错误
    • 备选：若一定要转义，写 \\$（YAML 把 \\ 解析为字面 \，最终值为 \$），但通常没必要
• 外部链接限制：禁止使用非 apiyi.com 域名的超链接，改为纯文本 + 反引号代码格式
  • ✅ 正确：谷歌官方博客：`blog.google/technology/ai/...`
  • ❌ 错误：谷歌官方博客：[链接](https://blog.google/...)
  • 原因：避免用户直接跳转到第三方网站，让用户主动复制链接访问
• 小于号转义：在 MDX/JSX 组件内使用小于号 < 时需要注意
  • ✅ 正确：建议少于20字 或 建议 < 20字
  • ❌ 错误：建议<20字（< 会被误认为 HTML 标签开始）
  • 原因：MDX 会将 < 后面的内容当作标签解析，导致解析错误
• JSX 属性内的引号：JSX 属性值用 "..." 包裹时，里面禁止再出现 ASCII 双引号 "
  • ✅ 正确：<Step title="prompt 聚焦「动作」而不是「画面」">（用中文引号 「」）
  • ✅ 正确：<Step title='prompt 聚焦"动作"而不是"画面"'>（外层换单引号）
  • ❌ 错误：<Step title="prompt 聚焦"动作"而不是"画面"">（第二个 " 提前闭合属性，后面的中文被当作 attribute name 解析报错）
  • 原因：MDX/JSX 不会自动识别”嵌套引号”，第二个 " 一定结束属性。中文场景优先用 「」，最直观无歧义
  • 同样适用于：解析失败时常常级联触发 docs.json 报告”file does not exist”，定位时优先排查最近一次编辑的 JSX 属性

​

Changelog 精简格式规范

​

设计理念

​

条目格式要求

### 🌟 [更新标题]
**YYYY年MM月DD日**

[2-3句话的核心摘要，突出关键信息]

📖 [查看详情](/news/文章slug) | 🔗 [相关文档](/docs/link)

​

摘要写作要点

• 第一句：说明是什么（新增模型/功能更新/价格调整等）
• 第二句：核心亮点（性能指标/价格优势/关键特性）
• 第三句：推荐场景或使用建议（可选）
• 长度控制：总计 50-80 字，不超过 3 句话
• Emoji使用：适当使用 emoji 增强可读性（🚀🎉💰🏆等）

​

链接规范

• 查看详情链接：必须链接到对应的 News 文章
• 相关文档链接：如有详细 API 文档，提供直达链接
• 格式统一：使用 📖 查看详情 和 🔗 相关文档 标识

​

示例（正确）

### 🌟 Gemini 3 Pro Preview 震撼上线
**2025年11月20日**

谷歌最新多模态智能模型上线！LMArena 排行榜 1501 Elo 全球第一，SWE-bench Verified 76.2%，支持 100 万上下文和思维链输出。充值加赠可达 8 折优惠。

📖 [查看详情](/news/gemini-3-pro-preview-launch) | 🔗 [API文档](/api-capabilities/gemini)

​

示例（错误 - 避免）

### 🌟 Gemini 3 Pro Preview 震撼上线
**2025年11月20日**

<Card>
  [大段详细内容...]  ← 不要在 Changelog 中使用 Card 组件展示详细信息
  [技术细节...]      ← 不要在 Changelog 中写太多技术细节
  [使用指南...]      ← 详细指南应该放在 News 文章中
</Card>

​

AI风向标（News）书写规范

​

栏目定位

• 本站更新：新模型上线、价格调整、功能更新的深度解读
• 行业动态：AI 领域重要事件、技术突破、趋势分析
• 使用指南：模型对比、最佳实践、应用案例

​

文章页面结构

---
title: "文章标题（20字以内，吸引眼球）"
description: "一句话摘要（50-80字，适合搜索引擎和社交分享）"
date: "2025-11-20"
author: "API易团队"
category: "site-update | industry-news | tutorial | model-release"
tags: ["标签1", "标签2", "标签3"]
icon: "newspaper"
featured: true  # 是否在首页展示
---

## 核心要点
[3-5个要点，用 bullet points 列出，让读者快速了解文章内容]

## 背景介绍
[为什么要关注这个话题？有什么背景信息？]

## 详细解析
[深入分析，包含技术细节、性能对比、使用场景等]

## 实际应用
[如何使用？代码示例、最佳实践]

## 价格与可用性
[定价信息、购买渠道、优惠活动]

## 总结与建议
[总结核心观点，给出使用建议]

​

写作风格指南

• 专业度：引用官方数据、权威评测、性能指标
• 易读性：使用副标题、要点列表、代码示例、对比表格
• 时效性：标注发布日期、版本号、数据来源日期
• 可操作性：提供具体的使用方法、代码示例、配置指南
• 视觉化：使用 Card、Info、Warning 等 Mintlify 组件增强可读性

​

联网搜索要求（必须）

• 创作前搜索：撰写每篇 News 文章前必须进行联网搜索
• 验证信息：核实模型发布日期、性能指标、官方公告
• 引用来源：标注信息来源（官方博客、技术报告、评测网站）
• 时效性检查：确保使用最新的版本号、API 端点、定价信息

​

分类标签系统（Tags）

• 类型标签：site-update（本站更新）、industry-news（行业动态）、tutorial（教程指南）、model-release（模型发布）
• 厂商标签：openai、google、anthropic、deepseek、zhipu 等
• 能力标签：text-generation、image-generation、video-generation、code、reasoning 等
• 使用场景：programming、translation、creative-writing、data-analysis 等

​

文件命名规范

• 格式：模型名-发布类型-日期.mdx
• 示例：
  • gemini-3-pro-preview-launch.mdx（模型发布）
  • gpt-5-price-update.mdx（价格更新）
  • ai-trends-2025-q4.mdx（行业趋势）
• 要求：小写字母、连字符分隔、简洁明了

​

目录组织

• 路径：/news/ 和 /en/news/（中英双语）
• 结构：扁平结构，所有文章在根目录
• 排序：通过 frontmatter 的 date 字段自动排序
• 分类：通过 tags 和 category 字段分类

​

与 Changelog 的关系

• Changelog：简短摘要（2-3句话）+ 链接到 News
• News：完整的深度文章（800-2000字）
• 链接：Changelog 条目必须链接到对应的 News 文章
• 同步更新：发布 News 文章时，同步更新 Changelog

​

Mintlify 组件使用

{/* 重要信息 */}
<Info>
  这里是重要提示信息
</Info>

{/* 警告提醒 */}
<Warning>
  注意事项和限制
</Warning>

{/* 要点卡片 */}
<Card title="核心特性" icon="star">
  特性说明
</Card>

{/* 多列布局 */}
<CardGroup cols={2}>
  <Card title="优势" icon="check">内容</Card>
  <Card title="限制" icon="ban">内容</Card>
</CardGroup>

{/* 代码示例 */}
```python
# Python 代码示例
import openai

### 图片使用规范
- 遵循"图片格式要求"章节的规范
- 优先使用 PNG 格式
- 支持浅色/深色主题切换
- 文件大小控制在 200KB 以内

### 质量检查清单
发布前检查：
- ✅ 已进行联网搜索验证信息
- ✅ Frontmatter 字段完整（title、description、date、tags 等）
- ✅ 无 H1 标题（使用 H2 起始）
- ✅ 代码示例可运行
- ✅ 链接有效（内部链接和外部链接）
- ✅ 图片正常显示
- ✅ 中英文版本同步
- ✅ Changelog 已更新对应链接
- ✅ **docs.json 导航配置已更新**（中英双版本，见下方说明）
- ✅ **价格符号已转义**（`$` → `\$`）
- ✅ **无外部超链接**（非 apiyi.com 域名改为纯文本 + 反引号）
- ✅ **小于号已处理**（`<数字` 改为 `少于数字` 或 `&lt;数字`）

### docs.json 导航更新（重要）
**每次创建新的 News 文章后必须更新 `docs.json`，否则用户无法在网站导航中找到新文章。**

#### 需要更新的位置
1. **中文版导航**（约第187-192行）：
   - 路径：`navigation.languages[0].tabs` → 找到 `"tab": "AI风向标"` → `groups[0].pages`
   - 在 `pages` 数组**最前面**添加：`"news/文章文件名"`（不含 `.mdx`）

2. **英文版导航**（约第552-557行）：
   - 路径：`navigation.languages[1].tabs` → 找到 `"tab": "AI Radar"` → `groups[0].pages`
   - 在 `pages` 数组**最前面**添加：`"en/news/文章文件名"`（不含 `.mdx`）

#### 示例
```json
{
  "pages": [
    "news/你的新文章-slug",  // 新文章置顶
    "news/seedream-4-5-launch",
    "news/claude-opus-4-5-launch"
  ]
}

​

注意事项

• 新文章必须放在数组最前面（最新的在最上面）
• 注意 JSON 逗号语法
• 中英文版本必须同时更新
• 路径不包含 .mdx 扩展名