跳转到主要内容

​
项目配置 - API易文档中心

​
项目概述

这是一个基于 Mintlify 的文档网站项目，为 API易 提供技术文档和FAQ支持。官网 https://mintlify.com/

​
文档编写规范

​
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、今晚六点半（缺少时区，全球客户无法判断）

​
大模型百科写作规范

​
词条页面结构

---
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注释语法
  • 价格符号转义：在 Markdown 表格或文本中使用 $ 符号时，必须转义为 \$，避免被误认为 LaTeX 数学模式
    • ✅ 正确：\$2.00 / 百万 tokens
    • ❌ 错误：$2.00 / 百万 tokens（会触发 LaTeX 解析错误）
  • 外部链接限制：禁止使用非 apiyi.com 域名的超链接，改为纯文本 + 反引号代码格式
    • ✅ 正确：谷歌官方博客：`blog.google/technology/ai/...`
    • ❌ 错误：谷歌官方博客：[链接](https://blog.google/...)
    • 原因：避免用户直接跳转到第三方网站，让用户主动复制链接访问
  • 小于号转义：在 MDX/JSX 组件内使用小于号 < 时需要注意
    • ✅ 正确：建议少于20字 或 建议 &lt; 20字
    • ❌ 错误：建议<20字（< 会被误认为 HTML 标签开始）
    • 原因：MDX 会将 < 后面的内容当作标签解析，导致解析错误

​
Changelog 精简格式规范

​
设计理念

Changelog 页面作为快速更新公告，应保持简洁明了。详细内容通过”AI风向标”（News）栏目展示。

​
条目格式要求

### 🌟 [更新标题]
**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风向标是独立的顶级导航栏目，用于发布：
  • 本站更新：新模型上线、价格调整、功能更新的深度解读
  • 行业动态：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
模型性能价格
A90%$1
B85%$0.5

### 图片使用规范
- 遵循"图片格式要求"章节的规范
- 优先使用 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 扩展名