Remotion 文档编写与修改指南。适用于新增文档页面、编辑 packages/docs 目录下的 MDX 文件或撰写文档内容时。
编写 Remotion 文档
文档存放在 packages/docs/docs 目录下，文件格式为 .mdx。
新增文档页面
- 在
packages/docs/docs目录下新建一个.mdx文件 - 将该文档配置添加到
packages/docs/sidebars.ts - 按照下文的规范撰写内容
- 在
packages/docs目录下运行bun render-cards.ts生成社交媒体预览卡片
面包屑导航（crumb）：如果文档页面属于某个特定的 package，请在 frontmatter 中添加 crumb: '@remotion/package-name'。这会在标题上方将 package 名称显示为面包屑。
---
image: /generated/articles-docs-my-package-my-api.png
title: '<MyComponent>'
crumb: '@remotion/my-package'
---
一页只写一个 API：每个函数或 API 都应该有自己专属的文档页面。不要把多个 API（例如 getEncodableVideoCodecs() 和 getEncodableAudioCodecs()）混在一个页面里写。
仅记录公开 API：文档只服务于公开 API。切勿提及、引用内部/私有 API 或实现细节，也不要拿它们做对比。
正文中的 API 名称：请用反引号包裹 API 名称；如果已有对应文档页，请加上链接。函数和 Hook 的名称必须带上 ()，例如 useVideoConfig()，而不是 useVideoConfig 或 useVideoConfig。组件名称必须包含尖括号，例如 <Player> 或 <Audio>。
各字段属性统一使用标题：在记录 API 的配置选项（options）或返回值时，每个属性都必须作为独立标题。顶层属性使用 ### 标题，options 对象内的嵌套属性使用 #### 标题。不要使用无序列表来列举单条属性。
版本标识：如果某个 API、功能、参数或行为是在特定版本中引入的，请在读者首次需要了解它的位置（页面、章节或字段标题处）添加 <AvailableFrom>。例如：# prefetch()<AvailableFrom v="4.0.0" />。
兼容性表格：API 页面最好在 ## See also 之前包含一个带有 <CompatibilityTable> 的 ## Compatibility 章节。
侧边栏排序逻辑：在 packages/docs/sidebars.ts 中添加或移动文档时，请检查上下文条目并保持已有的排序逻辑。如果某个章节是按字母顺序排列的，请按字母顺序插入新条目；如果是按工作流或重要性分组的，请保持相同的分组逻辑。切勿把新加内容随便挂在末尾成为孤立项。
语言风格规范
- 保持精炼：开发者不喜欢读长篇大论。多余的废话会导致关键信息丢失。
- 关联术语表：Remotion 专属术语请链接至 术语表 页面。
- 避免带有情感色彩的套话：删掉形如 "太棒了！接下来我们..." 这种充数废话——它们不会提供任何有用信息。
- 合理分段：避免出现过长的段落，及时拆分。
- 使用 "你"（第二人称）称呼读者：不要用 "我们"。
- 不要甩锅给用户：用 "输入无效"，而不是 "你输错了"。
- 不要主观假设操作很简单：少用 "只需"、"简单" 这种词——初学者可能会觉得有门槛。
代码片段
基础语法高亮：
```ts
const x = 1;
```
类型安全的代码片段（首选）
使用 twoslash 结合 TypeScript 对代码片段进行校验：
```ts twoslash
import {useCurrentFrame} from 'remotion';
const frame = useCurrentFrame();
```
隐藏 import 语句
使用 // ---cut--- 隐藏前置准备代码——展示时仅显示其下方的代码内容：
```ts twoslash
import {useCurrentFrame} from 'remotion';
// ---cut---
const frame = useCurrentFrame();
```
添加标题
为所有展示示例用法的代码块加上 title 属性：
```ts twoslash title="MyComponent.tsx"
console.log('Hello');
```
特殊组件
Steps 步骤组件
<Step> 附近的格式非常敏感。请保持每行包含一个步骤，在 </Step> 后面留一个空格；当步骤写为紧凑的单行内联列表时，必须保留显式的换行符（<br/> 或 <br />）。切勿写成没有空格的 <Step>1</Step>第一步。
- <Step>1</Step> 第一步
- <Step>2</Step> 第二步
Experimental Badge 实验性徽章
<ExperimentalBadge>
<p>This feature is experimental.</p>
</ExperimentalBadge>
Interactive Demos 交互式 Demo
<Demo type="rect"/>
Demo 必须在 packages/docs/components/demos/index.tsx 中实现。关于如何新增 Demo 的细节，请参见 docs-demo skill。
AvailableFrom
用于标注功能或参数是在哪个版本中引入的。全局可用，无需 import 引入。
对于页面级的版本标识，请使用带有 <AvailableFrom> 的 # h1 标题行内放置，使其直接贴在标题旁边（而不是放在标题下方）。组件名称中的尖括号需使用 < 和 > 转义：
# <MyComponent><AvailableFrom v="4.0.123" />
# @remotion/my-package<AvailableFrom v="4.0.123" />
对于章节标题：
## Saving to another cloud<AvailableFrom v="3.2.23" />
CompatibilityTable
用于标注组件或 API 支持哪些运行时和环境。无需 import 引入。请将其放在 ## See also 之前的 ## Compatibility 章节中。
可用的布尔属性（props）：chrome, firefox, safari, player, studio, clientSideRendering, serverSideRendering。设为 true 表示支持，设为 {false} 表示不支持。
如果是前端 API，不支持的选项设为空字符串 ""：nodejs="", bun="", serverlessFunctions=""。
如果是前端 API，可以使用 hideServers 隐藏 Node.js/Bun/serverless 这一行。
## Compatibility
<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio hideServers />
可选参数
在 API 文档中记录可选参数时：
- 在标题末尾添加
?—— 这表示该参数是可选的
--> 如果是 CLI flag（以--开头），不要加?—— CLI flag 默认都是可选的 - 切勿添加
_optional_文本 ——?后缀就已经足够了 - 在说明中包含默认值 —— 自然地在正文中提及
### onError?
Called when an error occurs. Default: errors are thrown.
切勿这样写：
### onError?
_optional_
Called when an error occurs.
组合使用可选参数与 AvailableFrom
当一个参数既是可选的，又是在特定版本中新增的时：
### onError?<AvailableFrom v="4.0.50" />
Called when an error occurs.
"Optional since" 模式
如果某个参数在特定版本变为了可选参数（此前为必填）：
### codec?
Optional since <AvailableFrom v="5.0.0" inline />. Previously required.
生成预览卡片
在新增或修改页面后，生成社交媒体预览卡片：
cd packages/docs && bun render-cards.ts
精简优化现存文档
在被要求审查（audit）或精简优化文档时，重点排查以下点：
- 特定版本引入的 API、功能、选项、参数或行为，是否遗漏了
<AvailableFrom>标识 - API 名称是否没有格式化为代码行内 span，或者没有加上对应文档页面的链接
- 函数和 Hook 引用是否漏掉了
() - 应该包含
## Compatibility章节（及<CompatibilityTable>）的 API 页面是否遗漏了该内容 <Step>的格式是否存在隐患或损坏
