Writing Docs

1---2name: writing-docs3description: Guides for writing and editing Remotion documentation. Use when adding docs pages, editing MDX files in packages/docs, or writing documentation content.4---5 6# Writing Remotion Documentation7 8Documentation lives in `packages/docs/docs` as `.mdx` files.9 10## Adding a new page11 121. Create a new `.mdx` file in `packages/docs/docs`132. Add the document to `packages/docs/sidebars.ts`143. Write the content following guidelines below154. Run `bun render-cards.ts` in `packages/docs` to generate social preview cards16 17**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.18 19```md20---21image: /generated/articles-docs-my-package-my-api.png22title: '<MyComponent>'23crumb: '@remotion/my-package'24---25```26 27**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.28 29**Public API only**: Documentation is for public APIs only. Do not mention, reference, or compare against internal/private APIs or implementation details.30 31**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.32 33## Language guidelines34 35- **Keep it brief**: Developers don't like to read. Extra words cause information loss.36- **Link to terminology**: Use [terminology](/docs/terminology) page for Remotion-specific terms.37- **Avoid emotions**: Remove filler like "Great! Let's move on..." - it adds no information.38- **Separate into paragraphs**: Break up long sections.39- **Address as "you"**: Not "we".40- **Don't blame the user**: Say "The input is invalid" not "You provided wrong input".41- **Don't assume it's easy**: Avoid "simply" and "just" - beginners may struggle.42 43## Code snippets44 45Basic syntax highlighting:46 47````md48```ts49const x = 1;50```51````52 53### Type-safe snippets (preferred)54 55Use `twoslash` to check snippets against TypeScript:56 57````md58```ts twoslash59import {useCurrentFrame} from 'remotion';60const frame = useCurrentFrame();61```62````63 64### Hiding imports65 66Use `// ---cut---` to hide setup code - only content below is displayed:67 68````md69```ts twoslash70import {useCurrentFrame} from 'remotion';71// ---cut---72const frame = useCurrentFrame();73```74````75 76### Adding titles77 78Always add a `title` to code fences that show example usage:79 80````md81```ts twoslash title="MyComponent.tsx"82console.log('Hello');83```84````85 86## Special components87 88### Steps89 90```md91- <Step>1</Step> First step92- <Step>2</Step> Second step93```94 95### Experimental badge96 97```md98<ExperimentalBadge>99<p>This feature is experimental.</p>100</ExperimentalBadge>101```102 103### Interactive demos104 105```md106<Demo type="rect"/>107```108 109Demos must be implemented in `packages/docs/components/demos/index.tsx`. See the `docs-demo` skill for details on adding new demos.110 111### AvailableFrom112 113Use to indicate when a feature or parameter was added. No import needed - it's globally available.114 115**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:116 117```md118# &lt;MyComponent&gt;<AvailableFrom v="4.0.123" />119```120 121```md122# @remotion/my-package<AvailableFrom v="4.0.123" />123```124 125For section headings:126 127```md128## Saving to another cloud<AvailableFrom v="3.2.23" />129```130 131### CompatibilityTable132 133Use to indicate which runtimes and environments a component or API supports. No import needed. Place it in a `## Compatibility` section before `## See also`.134 135Available boolean props: `chrome`, `firefox`, `safari`, `player`, `studio`, `clientSideRendering`, `serverSideRendering`. Set to `true` (supported) or `{false}` (not supported).136 137Set to empty string `""` for not applicable if this is a frontend API: `nodejs=""`, `bun=""`, `serverlessFunctions=""`.138Use `hideServers` to hide the Node.js/Bun/serverless row if this is a frontend API.139 140```md141## Compatibility142 143<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio hideServers />144```145 146### Optional parameters147 148For optional parameters in API documentation:149 1501. **Add `?` to the heading** - this indicates the parameter is optional151   --> Don't do it if it is a CLI flag (beginning with `--`) - CLI flags are always optional1522. **Do NOT add `_optional_` text** - the `?` suffix is sufficient1533. **Include default value in description** - mention it naturally in the text154 155```md156### onError?157 158Called when an error occurs. Default: errors are thrown.159```160 161**Do NOT do this:**162 163```md164### onError?165 166_optional_167 168Called when an error occurs.169```170 171### Combining optional and AvailableFrom172 173When a parameter is both optional and was added in a specific version:174 175```md176### onError?<AvailableFrom v="4.0.50" />177 178Called when an error occurs.179```180 181### "Optional since" pattern182 183If a parameter became optional in a specific version (was previously required):184 185```md186### codec?187 188Optional since <AvailableFrom v="5.0.0" inline />. Previously required.189```190 191## Generating preview cards192 193After adding or editing a page, generate social media preview cards:194 195```bash196cd packages/docs && bun render-cards.ts197```198 199## Verifying docs compile200 201To check that documentation builds without errors:202 203```bash204# from the monorepo root205bun run build-docs206```207 208This validates MDX syntax, twoslash snippets, and broken links.