writing-docs

编写 Remotion 文档

文档以 .mdx 文件的形式存放在 packages/docs/docs 中。

添加新页面

1. 在 packages/docs/docs 中创建一个新的 .mdx 文件
2. 将文档添加到 packages/docs/sidebars.ts
3. 按照以下指南编写内容
4. 在 packages/docs 中运行 bun render-cards.ts，生成社交媒体预览卡片

面包屑（crumb）：如果文档页面属于某个包，请在 frontmatter 中添加 crumb: '@remotion/package-name'。这会在标题上方显示包名作为面包屑。

---
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 选项或返回值时，每个属性都应使用自己的标题。顶层属性使用 ###，选项对象中的嵌套属性使用 ####。不要用项目符号列出单个字段。

版本标记：如果某个 API、功能、参数或行为是在特定版本中新增的，请在读者首次需要了解它的位置添加 <AvailableFrom>，可以放在页面、章节或字段中。例如：# prefetch()<AvailableFrom v="4.0.0" />。

兼容性表格：API 页面最好包含 ## Compatibility 章节，并在 ## See also 之前添加 <CompatibilityTable>。

侧边栏顺序：在 packages/docs/sidebars.ts 中添加或移动文档时，请检查周围的条目，并遵循已有的排序逻辑。如果某个章节按字母顺序排列，请按字母顺序放置新条目；如果按工作流或重要性分组，请与该分组保持一致。不要让新增条目显得格格不入。

语言指南

• 简洁明了：开发者不喜欢阅读冗长内容。多余的文字会导致信息流失。
• 链接到术语：使用 terminology 页面中的 Remotion 专有术语。
• 不要加粗术语：根据需要，将术语写为普通文本、代码片段或链接。不要用粗体格式引出术语。
• 避免情绪化表达：删除“太棒了！我们继续……”之类的填充语，这些内容没有提供信息。
• 分段：将较长的章节拆分成多个段落。
• 使用“你”称呼读者：不要使用“我们”。
• 不要责怪用户：说“输入无效”，而不是“你提供了错误的输入”。
• 不要假设操作很简单：避免使用“简单地”和“只需”等说法，新手可能会觉得有难度。

代码片段

基本语法高亮：

```ts
const x = 1;
```

类型安全的代码片段（推荐）

使用 twoslash 检查代码片段是否符合 TypeScript 类型：

```ts twoslash
import {useCurrentFrame} from 'remotion';
const frame = useCurrentFrame();
```

隐藏导入

使用 // ---cut--- 隐藏设置代码——仅显示其下方的内容：

```ts twoslash
import {useCurrentFrame} from 'remotion';
// ---cut---
const frame = useCurrentFrame();
```

添加标题

展示示例用法的代码围栏始终要添加 title：

```ts twoslash title="MyComponent.tsx"
console.log('Hello');
```

特殊组件

步骤

每行放置一个 <Step>，并在 </Step> 后添加一个空格。连续的步骤需要分行显示时，请使用显式换行（<br/> 或 <br />）。不要仅为将步骤包裹在 <ul> 中而添加 Markdown 项目符号。

<Step>1</Step> First step<br />
<Step>2</Step> Second step

实验性徽标

<ExperimentalBadge>
<p>This feature is experimental.</p>
</ExperimentalBadge>

交互式演示

<Demo type="rect"/>

演示必须在 packages/docs/components/demos/index.tsx 中实现。有关添加新演示的详细信息，请参阅 docs-demo 技能。

AvailableFrom

用于标明某项功能或参数的新增时间。无需导入，全局可用。

对于页面级版本指示器，请使用带有内联 <AvailableFrom> 的 # h1 标题，使其显示在标题旁边（而非下方）。使用 < 和 > 转义组件名称中的尖括号：

# &lt;MyComponent&gt;<AvailableFrom v="4.0.123" />

# @remotion/my-package<AvailableFrom v="4.0.123" />

对于章节标题：

## Saving to another cloud<AvailableFrom v="3.2.23" />

CompatibilityTable

用于标明组件或 API 支持哪些运行时和环境。无需导入。请将其放在 ## Compatibility 章节中，并置于 ## See also 之前。

可用的布尔属性：chrome、firefox、safari、player、studio、clientSideRendering、serverSideRendering。设为 true 表示支持，设为 {false} 表示不支持。

如果这是前端 API，则将不适用的属性设为空字符串 ""：nodejs=""、bun=""、serverlessFunctions=""。 如果这是前端 API，请使用 hideServers 隐藏 Node.js/Bun/无服务器函数这一行。

## Compatibility

<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio hideServers />

可选参数

对于 API 文档中的可选参数：

1. 在标题中添加 ?——这表示该参数是可选的 --> 如果是 CLI 标志（以 -- 开头），则不要这样做——CLI 标志始终是可选的
2. 不要添加 _optional_ 文本——? 后缀已经足够
3. 在说明中包含默认值——在文本中自然地提及

### 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.

“自某版本起可选”模式

如果某个参数从特定版本起变为可选（此前为必需参数）：

### codec?

Optional since <AvailableFrom v="5.0.0" inline />. Previously required.

生成预览卡片

添加或编辑页面后，请生成社交媒体预览卡片：

cd packages/docs && bun render-cards.ts

精简现有文档

收到审查或精简文档的请求时，请检查：

• API、功能、选项、参数或行为缺少 <AvailableFrom> 指示器，而它们是在特定版本中引入的
• API 名称未使用代码行内格式，也未链接到其文档页面
• 函数和 Hook 引用缺少 ()
• API 页面应包含 <CompatibilityTable>，但缺少 ## Compatibility 章节
• <Step> 格式容易出错或已损坏