CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

writing-docs

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

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

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: 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 &lt; and &gt; to escape angle brackets in component names:

# &lt;MyComponent&gt;<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:

  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
### 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 ## Compatibility section with <CompatibilityTable>
  • Fragile or broken <Step> formatting
Repository

remotion-dev/remotion

Path

.agents/skills/writing-docs/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.