撰寫與編輯 Remotion 文件的指南。適用於新增文件頁面、編輯 packages/docs 中的 MDX 檔案，或撰寫文件內容時。
撰寫 Remotion 文件
文件以 .mdx 檔案形式存放於 packages/docs/docs。
新增頁面
- 在
packages/docs/docs中建立新的.mdx檔案 - 將該文件新增至
packages/docs/sidebars.ts - 按照下方指南撰寫內容
- 在
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：文件僅適用於公開（Public）API。請勿提及、參考或比較內部／私有（Internal/Private）API 或實作細節。
內文中的 API 名稱：請將 API 名稱放在反引號中；若有對應的文件頁面，請加上連結。函式與 Hook 名稱應包含 ()，例如 useVideoConfig()，而非 useVideoConfig 或 useVideoConfig。元件名稱應包含角括號，例如 <Player> 或 <Audio>。
所有欄位皆使用標題：撰寫 API 選項或回傳值的說明時，每個屬性都應獨立成一個標題。頂層屬性使用 ###，選項物件內的巢狀屬性使用 ####。請勿使用項目符號清單來列出個別欄位。
版本標示：若某個 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>Add...。
- <Step>1</Step> First step
- <Step>2</Step> Second step
實驗性功能徽章（Experimental badge）
<ExperimentalBadge>
<p>This feature is experimental.</p>
</ExperimentalBadge>
互動式 Demo
<Demo type="rect"/>
Demo 必須實作於 packages/docs/components/demos/index.tsx。有關新增 Demo 的詳細資訊，請參閱 docs-demo skill。
AvailableFrom
用於標示某個功能或參數是在哪個版本新增的。無需 Import——全域皆可直接使用。
頁面級別的版本標示：請使用 # h1 標題並在同行內嵌 <AvailableFrom>，使其顯示在標題旁邊（而非下方）。元件名稱中的角括號請使用 < 與 > 進行跳脫：
# <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 支援哪些執行階段（Runtime）與環境。無需 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 旗標（以--開頭）則無需加上?— CLI 旗標皆預設為可選 - 請勿新增
_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.
「自特定版本起改為可選」模式
若某個參數自特定版本起變更為可選（先前為必填）：
### codec?
Optional since <AvailableFrom v="5.0.0" inline />. Previously required.
生成預覽卡片
新增或編輯頁面後，請生成社群媒體預覽卡片：
cd packages/docs && bun render-cards.ts
精簡與審查現有文件
當獲知要審查或精簡文件時，請檢查以下項目：
- 於特定版本引進的 API、功能、選項、參數或行為，是否漏掉
<AvailableFrom>標示 - API 名稱是否未格式化為程式碼區段（Code span）或未連結至對應的文件頁面
- 函式與 Hook 參照是否漏掉了
() - API 頁面是否缺少帶有
<CompatibilityTable>的## Compatibility章節 <Step>格式是否有易碎或損壞的情形
