Writing Remotion Documentation
Documentation lives in packages/docs/docs as .mdx files.
Adding a new page
- Create a new
.mdxfile inpackages/docs/docs - Add the document to
packages/docs/sidebars.ts - Write the content following guidelines below
- Run
bun render-cards.tsinpackages/docsto 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: https://remotion.media/docs/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.
API names in prose: Put API names in backticks, and link them if a docs page exists. Function and hook names should include (), for example useVideoConfig(), not useVideoConfig or useVideoConfig. Components should include angle brackets, for example <Player> or <Audio>.
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.
Version indicators: If an API, feature, parameter, or behavior was added in a specific version, add <AvailableFrom> to the heading of the page, section, or field where the reader first needs to know it. For example: # prefetch()<AvailableFrom v="4.0.0" />. Only use <AvailableFrom> in headings; in prose, lists and tables, write the version as plain text, for example "From v4.0.540, ...".
Compatibility tables: API pages should ideally include a ## Compatibility section with <CompatibilityTable> before ## See also.
Sidebar order: When adding or moving docs in packages/docs/sidebars.ts, inspect the surrounding entries and match the ordering logic already used there. If a section is alphabetical, place the new entry alphabetically; if it is grouped by workflow or importance, place it consistently with that grouping. Do not leave new additions as one-off outliers.
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.
- Do not bold terms: Write terms as plain text, code spans, or links as appropriate. Do not use bold formatting to introduce a term.
- Use sentence case: Page titles, headings and option names capitalize only the first word, as in "Audio codec", not "Audio Codec". Proper nouns and product names keep their capitalization, as in "Enable Lambda Insights" or "Override FPS".
- Avoid emotions: Remove filler like "Great! Let's move on..." - it adds no information.
- Separate into paragraphs: Break up long sections.
- 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.
Voice: "we" and "you"
A reader of a guide or an example hasn't decided to do anything yet. Don't assign them an intent, an action or knowledge with "you".
- Describe examples and code by what they do. Make the example, the code or the value the subject.
- Bad: "In this example, you are interpolating colors. At frame 0, you want the color to be red."
- Good: "This example interpolates colors. At frame 0, the color should be red."
- Bad: "Add
userSelect: 'none'to disable selection." (explaining code that is already shown) - Good: "
userSelect: 'none'disables selection."
- Use the imperative for steps the reader is actively following, such as "Click Render" or "Run
npx remotion lambda sites create". - Use "you" for the reader's real options, choices and situation: "Allows you to…", "If you want to…", "You can use any web framework…", "your project".
- Don't tell the reader what they want, need or know: write "it is not needed" or "requires some code", not "you don't need it" or "you need to write some code".
- Use "we" for the Remotion team: recommendations ("We recommend…"), plans, hopes, and what the team does to the product ("As we test it, we might change the API"). Prefer this over passive voice ("This issue is hoped to be fixed soon") or "Remotion recommends".
- Use "Let's" only to open a guided walkthrough, such as "Let's build the demo above.", not as filler.
Code snippets
Basic syntax highlighting:
```ts
const x = 1;
```
Type-safe snippets (preferred)
Use twoslash to check snippets against 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();
```
Adding titles
Always add a title to code fences that show example usage:
```ts twoslash title="MyComponent.tsx"
console.log('Hello');
```
Special components
Steps
Keep one <Step> per line and add a space after </Step>. Use an explicit line break (<br/> or <br />) when consecutive steps should appear on separate lines. Do not add Markdown bullet markers solely to wrap steps in a <ul>.
<Step>1</Step> First step<br />
<Step>2</Step> Second step
Experimental badge
<ExperimentalBadge>
<p>This feature is experimental.</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.
AvailableFrom
Use to indicate when a feature or parameter was added. No import needed - it's globally available.
Only place <AvailableFrom> at the end of a heading. Never use it inside a sentence, list item or table cell - the badge looks out of place there. If a behavior changed in a specific version and does not have its own heading, write the version as plain text instead:
From v4.0.540, you can override the name.
Do not do this:
From <AvailableFrom v="4.0.540" inline />, you can override the name.
For page-level version indicators, use an # h1 heading with <AvailableFrom> inline so it appears next to the title (not below it). Use < and > to escape angle brackets in component names:
# <MyComponent><AvailableFrom v="4.0.123" />
# @remotion/my-package<AvailableFrom v="4.0.123" />
For section headings:
## Saving to another cloud<AvailableFrom v="3.2.23" />
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.
## 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
### onError?
Called when an error occurs. Default: errors are thrown.
Do NOT do this:
### onError?
_optional_
Called when an error occurs.
Combining optional and AvailableFrom
When a parameter is both optional and was added in a specific version:
### onError?<AvailableFrom v="4.0.50" />
Called when an error occurs.
"Optional since" pattern
If a parameter became optional in a specific version (was previously required), write the version as plain text:
### codec?
Optional since v5.0.0. Previously required.
Generating preview cards
After adding or editing a page, generate social media preview cards:
cd packages/docs && bun render-cards.ts
The command uploads cards to https://remotion.media/docs/generated/ and
requires R2 credentials from the docs environment or bun --env-file.
Commit the hosted image: frontmatter; local generated PNGs are ignored.
To replace an existing card, pass --overwrite=<composition-id>.
Streamlining existing docs
When asked to audit or streamline docs, scan for:
- Missing
<AvailableFrom>indicators for APIs, features, options, parameters, or behaviors introduced in a specific version - API names that are not formatted as code spans or linked to their docs page
- Function and hook references missing
() - API pages that should have a
## Compatibilitysection with<CompatibilityTable> - Fragile or broken
<Step>formatting
