Guides for writing and editing Remotion documentation. Use when adding docs pages, editing MDX files in packages/docs, or writing documentation content.

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. 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() ](/docs/use video config), not useVideoConfig or useVideoConfig. Components should include angle brackets, for example [ <Player ](/docs/player/player) or [ <Audio ](/docs/media/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](/docs/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. Avoid emotions : Remove filler like "Great! Let's move on..." it adds no information. Separate into paragraphs : Break up long sections. Address as "you" : Not "we". 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. 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 . Experimental badge Interactive demos 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. 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: For section headings: 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. Optional parameters For optional parameters in API documentation: 1. 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 2. Do NOT add optional text the ? suffix is sufficient 3. Include default value in description mention it naturally in the text Do NOT do this: Combining optional and AvailableFrom When a parameter is both optional and was added in a specific version: "Optional since" pattern If a parameter became optional in a specific version (was previously required): Generating preview cards After adding or editing a page, generate social media preview cards: 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 Compatibility section with <CompatibilityTable Fragile or broken <Step formatting

writing-docs