Writing Remotion Documentation

Writing Remotion Documentation

Documentation lives in packages/docs/docs as .mdx files.

Adding a new page

1. Create a new .mdx file in packages/docs/docs
2. Add the document to packages/docs/sidebars.ts
3. Write the content following guidelines below
4. 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.

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> at the page, section, or field where the reader first needs to know it. For example: # prefetch()<AvailableFrom v="4.0.0" />.

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.