跳到主要内容

内容风格指南

所有级别

一致性正是让参考资料显得值得信赖的关键。遵循这些，你的 PR 会顺利通过审阅。

语气​

  • 清晰而直接。 句子要短。开门见山。
  • 友好，但绝不空洞。 删掉“在当今快节奏的世界里”这类话。尊重读者的时间。
  • 先给观点，然后保持诚实。 先给出唯一推荐做法，再说明替代方案与取舍。
  • 例子胜过理论。 展示一段代码或一个具体案例；不要只做描述。
  • 使用美式英语。

页面结构​

---
sidebar_position: 2
title: "Your Page Title"
description: "One sentence for search and previews."
---

<LevelBadge level="beginner" />

A one or two sentence intro that states what the reader will get.

## Sections with ## headings
...

## Next
- 2–4 links to related pages
  • 以级别徽章开头（beginner | intermediate | advanced | all）。组件是全局的——不要导入它们。
  • 以“下一步”／“相关” 列表结尾，包含 2–4 个内部链接。
  • 使用警示框（:::tip、:::warning、:::note、:::info）来强调，但要节制。

两条硬性规则​

:::warning 不可妥协

  1. 为易变事实引用来源。 模型名称、价格、限制、确切参数、测试版功能 → 链接官方来源并加上 <VerifyNote lastVerified="YYYY-MM-DD" source="…">。切勿硬编码模型相关事实——链接到模型表。详见事实核实。
  2. 不要捏造。 不要编造统计数据、引文、API 或功能。如果不确定，就说明，或标记 [verify]。 :::

观点 vs 官方​

  • 我们是有观点的——这正是价值所在。要给出推荐，而不只是罗列。
  • 但官方文档是事实的唯一来源。 要尊重它们、链接到它们，绝不悄悄与它们相矛盾。

MDX 易错点​

  • 正文中的花括号 {like this} 会被 MDX 当作代码解析——把它们放进反引号或代码块里，或在示例中改用 [方括号]。
  • 在本地测试：npm run build 必须通过（链接失效会让它失败）。

下一步​