writing-docs

Remotion ドキュメントの作成

ドキュメントは packages/docs/docs にある .mdx ファイルです。

新しいページの追加

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 を 1 つ掲載：各関数または API には専用のドキュメントページを用意します。複数の API（例：getEncodableVideoCodecs() と getEncodableAudioCodecs()）を 1 つのページにまとめないでください。

公開 API のみ：ドキュメントの対象は公開 API のみです。内部 API や非公開 API、実装の詳細について言及、参照、比較しないでください。

文章内の API 名：API 名はバッククォートで囲み、ドキュメントページがある場合はリンクを設定します。関数名とフック名には () を付けます。たとえば、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();
```

インポートを非表示にする

// ---cut--- を使用してセットアップコードを非表示にします。表示されるのはその下の内容だけです。

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

タイトルを追加する

使用例を示すコードフェンスには、必ず title を追加します。

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

特殊コンポーネント

ステップ

<Step> は 1 行に 1 つ記述し、</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

機能またはパラメーターが追加された時期を示すために使用します。インポートは不要で、グローバルに利用できます。

ページレベルのバージョン表示には、# h1 見出し内に <AvailableFrom> を配置して、タイトルの横に表示されるようにします（タイトルの下には配置しません）。コンポーネント名の山括弧をエスケープするには、< と > を使用します。

# &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 がサポートするランタイムと環境を示すために使用します。インポートは不要です。## See also の前にある ## Compatibility セクションに配置します。

利用可能なブール型の props：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 />

Optional parameters

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 名がないか
• () が付いていない関数やフックへの参照がないか
• <CompatibilityTable> を含む ## Compatibility セクションを設けるべき API ページがないか
• 壊れやすい、または壊れている <Step> の書式がないか