writing-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Remotion Documentation

Remotion 文档编写指南

Documentation lives in

packages/docs/docs

.mdx

files.

文档以

.mdx

文件形式存储在

packages/docs/docs

目录下。

Adding a new page

添加新页面

Create a new
```
.mdx
```
file in
```
packages/docs/docs
```
Add the document to
```
packages/docs/sidebars.ts
```
Write the content following guidelines below
Run
```
bun render-cards.ts
```
in
```
packages/docs
```
to generate social preview cards

Breadcrumb (
crumb
): If a documentation page belongs to a package, add

crumb: '@remotion/package-name'

to the frontmatter. This displays the package name as a breadcrumb above the title.

---
image: /generated/articles-docs-my-package-my-api.png
title: '<MyComponent>'
crumb: '@remotion/my-package'
---

One API per page: Each function or API should have its own dedicated documentation page. Do not combine multiple APIs (e.g.,

getEncodableVideoCodecs()

and

getEncodableAudioCodecs()

) on a single page.

Public API only: Documentation is for public APIs only. Do not mention, reference, or compare against internal/private APIs or implementation details.

Use headings for all fields: When documenting API options or return values, each property should be its own heading. Use

###

for top-level properties and

####

for nested properties within an options object. Do not use bullet points for individual fields.

在
```
packages/docs/docs
```
目录下创建新的
```
.mdx
```
文件
将文档添加到
```
packages/docs/sidebars.ts
```
中
按照下方指南撰写内容
在
```
packages/docs
```
目录下运行
```
bun render-cards.ts
```
生成社交预览卡片

面包屑（
crumb
）：如果文档页面属于某个包，请在前置元数据中添加

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选项或返回值时，每个属性都应作为独立标题。顶层属性使用

###

，选项对象中的嵌套属性使用

####

。请勿对单个字段使用项目符号。

Language guidelines

语言规范

Keep it brief: Developers don't like to read. Extra words cause information loss.
Link to terminology: Use terminology page for Remotion-specific terms.
Avoid emotions: Remove filler like "Great! Let's move on..." - it adds no information.
Separate into paragraphs: Break up long sections.
Address as "you": Not "we".
Don't blame the user: Say "The input is invalid" not "You provided wrong input".
Don't assume it's easy: Avoid "simply" and "just" - beginners may struggle.

保持简洁：开发者不喜欢冗长的内容。多余的文字会导致信息丢失。
术语链接：Remotion特定术语请链接到术语表页面。
避免情绪化表达：删除诸如“太棒了！让我们继续...”之类的填充内容——它们没有任何信息价值。
分段展示：拆分长段落。
以“你”称呼读者：不要用“我们”。
不要指责用户：要说“输入无效”而非“你提供了错误的输入”。
不要假设内容简单：避免使用“只需”“简单地”等词汇——初学者可能会觉得困难。

Code snippets

代码片段

Basic syntax highlighting:

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

基础语法高亮：

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

Type-safe snippets (preferred)

类型安全片段（推荐）

Use

twoslash

to check snippets against TypeScript:

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

使用

twoslash

检查片段是否符合TypeScript规范：

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

Hiding imports

隐藏导入代码

Use

// ---cut---

to hide setup code - only content below is displayed:

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

使用

// ---cut---

隐藏设置代码——仅显示下方内容：

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

Adding titles

添加标题

Always add a

title

to code fences that show example usage:

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

对于展示示例用法的代码块，务必添加

title

：

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

Special components

特殊组件

Steps

步骤组件

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

- <Step>1</Step> 第一步
- <Step>2</Step> 第二步

Experimental badge

实验特性徽章

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

<ExperimentalBadge>
<p>此特性为实验性。</p>
</ExperimentalBadge>

Interactive demos

交互式演示

<Demo type="rect"/>

Demos must be implemented in

packages/docs/components/demos/index.tsx

. See the

docs-demo

skill for details on adding new demos.

<Demo type="rect"/>

演示必须在

packages/docs/components/demos/index.tsx

中实现。有关添加新演示的详情，请查看

docs-demo

技能文档。

AvailableFrom

AvailableFrom组件

Use to indicate when a feature or parameter was added. No import needed - it's globally available.

For page-level version indicators, use an

# h1

heading with

<AvailableFrom>

inline so it appears next to the title (not below it). Use

&lt;

and

&gt;

to escape angle brackets in component names:

undefined

用于标识特性或参数的添加版本。无需导入——它是全局可用的。

页面级版本标识：在

# h1

标题中内联使用

<AvailableFrom>

，使其显示在标题旁（而非下方）。使用

&lt;

和

&gt;

转义组件名称中的尖括号：

undefined

<MyComponent><AvailableFrom v="4.0.123" />


```md


```md

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


For section headings:

```md


对于章节标题：

```md

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

保存到其他云平台<AvailableFrom v="3.2.23" />

undefined

undefined

CompatibilityTable

CompatibilityTable组件

Use to indicate which runtimes and environments a component or API supports. No import needed. Place it in a

## Compatibility

section before

## See also

Available boolean props:

chrome

firefox

safari

player

studio

clientSideRendering

serverSideRendering

. Set to

true

(supported) or

{false}

(not supported).

Set to empty string

""

for not applicable if this is a frontend API:

nodejs=""

bun=""

serverlessFunctions=""

. Use

hideServers

to hide the Node.js/Bun/serverless row if this is a frontend API.

undefined

用于标识组件或API支持的运行时和环境。无需导入。请将其放在

## 兼容性

章节中，位于

## 另请参阅

之前。

可用布尔属性：

chrome

、

firefox

、

safari

、

player

、

studio

、

clientSideRendering

、

serverSideRendering

。设置为

true

（支持）或

{false}

（不支持）。

如果是前端API，将不适用的属性设为空字符串

""

：

nodejs=""

、

bun=""

、

serverlessFunctions=""

。如果是前端API，使用

hideServers

隐藏Node.js/Bun/无服务器行。

undefined

Compatibility

兼容性

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

Optional parameters

可选参数

For optional parameters in API documentation:

Add
?
to the heading - this indicates the parameter is optional --> Don't do it if it is a CLI flag (beginning with
```
--
```
) - CLI flags are always optional
Do NOT add
_optional_
text - the
```
?
```
suffix is sufficient
Include default value in description - mention it naturally in the text

undefined

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

在标题中添加
?
——这表示该参数是可选的 --> 如果是CLI标志（以
```
--
```
开头）则无需添加——CLI标志始终是可选的
不要添加
_optional_
文本——
```
?
```
后缀已足够说明
在描述中包含默认值——在文本中自然提及

undefined

onError?

Called when an error occurs. Default: errors are thrown.


**Do NOT do this:**

```md

发生错误时触发。默认值：抛出错误。


**请勿这样做：**

```md

onError?

optional

Called when an error occurs.

undefined

optional

发生错误时触发。

undefined

Combining optional and AvailableFrom

结合可选参数与AvailableFrom

When a parameter is both optional and was added in a specific version:

undefined

当参数既是可选的又是在特定版本中添加时：

undefined

onError?<AvailableFrom v="4.0.50" />

Called when an error occurs.

undefined

发生错误时触发。

undefined

"Optional since" pattern

“自某版本起可选”模式

If a parameter became optional in a specific version (was previously required):

undefined

如果参数在特定版本后变为可选（之前是必填的）：

undefined

codec?

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

undefined

自 <AvailableFrom v="5.0.0" inline /> 起变为可选。此前为必填。

undefined

Generating preview cards

生成预览卡片

After adding or editing a page, generate social media preview cards:

bash

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

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

bash

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

Verifying docs compile

验证文档编译

To check that documentation builds without errors:

bash

undefined

要检查文档是否能无错误构建：

bash

undefined

from the monorepo root

从单仓库根目录执行

bun run build-docs


This validates MDX syntax, twoslash snippets, and broken links.

bun run build-docs


这会验证MDX语法、twoslash片段和失效链接。