Skip to main content
Add interactive pages to let your readers click through a flow, add widgets, or watch your product work. This guide covers four building blocks for those pages:
  1. Interactive widgets written into the page as React components.
  2. Videos of the product, or of an agent session, recorded with a browser script.
  3. Screenshots in frames, with light and dark versions.
  4. Tables for status, limits, and comparisons.
The products, numbers, and steps in the examples in this guide are sample data.

Choose a building block

Interactive widgets

A widget is a React component declared in the page with export const, then placed with a tag like <RxJourney />. Put the component definitions at the end of the file so the content reads top to bottom. See React components for what the MDX environment supports.

Click through a flow

Use a stepper when a process has a clear order. Each step names who acts and what happens.

Try your own numbers

Use a calculator when the answer depends on the reader’s inputs. Show the formula in the result, so readers can check it.

Show a trend

Use a chart with a toggle when readers switch between a few related series. Keep it to one question per chart.

How the calculator works

This is the complete source of the calculator. The plan buttons, sliders, and result all read from state, and the total is computed during render.
usage.mdx

Widget guidelines

  • Make every color work in light and dark mode. Use currentColor or inherit for text and lines, translucent grays like rgba(127,127,127,.25) for borders and fills, and one accent color. Avoid fixed black or white.
  • Add className="not-prose" to the outer element so the page’s typography styles don’t change spacing inside the widget.
  • Write data into the component as constants. Don’t fetch data or use localStorage, sessionStorage, or cookies, because those fail or do nothing in the editor.
  • Write plain JavaScript. A TypeScript annotation breaks the whole page on your published site.
  • Put links in the prose around a widget. Links inside a widget don’t navigate in the editor.
  • Give each page’s components a short shared prefix, like Rx, so their names don’t collide with built-in components or with each other.
  • Give buttons and inputs visible labels or an aria-label, and mark the selected option with aria-pressed or aria-current.
  • Keep a page to a handful of widgets. The editor runs at most 10 widgets at a time and pauses the rest until they scroll into view.
  • To use a widget on more than one page, move it to a file in /snippets/ and import it. See Reusable snippets.

Videos

Record a short video when readers need to see something move: a walkthrough of a UI, a deployment finishing, or an agent working through a task. Muted videos that loop work like animated screenshots. Keep self-hosted clips short and small, and host longer videos on a platform like YouTube. See Media for when to use video and how to keep file sizes down.

Record the product with a script

A browser script gives you the same video every time, so you can record it again after the UI changes. This Playwright script records a WebM file while it clicks through a flow:
record.mjs
Tips for readable recordings:
  • Pause for about a second after each action, so readers can follow the change.
  • Type with a delay instead of filling fields instantly.
  • Keep videos under 30 seconds. Split longer flows into several videos next to the steps they show.
  • Use sample accounts and data, never production data.

Replay an agent session

To show what an agent did, record its session and play it back as a video. Claude Code and Codex can write the session as JSON lines, for example claude -p "<task>" --output-format stream-json --verbose > session.jsonl. Render the messages and tool calls into a simple terminal-style HTML page, then record that page with the Playwright script. A replay shows the real commands and the order the agent ran them in, without exposing a live terminal.

Screenshots

Put screenshots in a <Frame> with a caption that says what to look at. Crop to the part of the screen that matters.
To keep screenshots current, take them with a script. Use the same Playwright setup as the video script, call page.screenshot({ path: "images/settings-light.png" }), and run it again when the UI changes. For the dark version, create the context with colorScheme: "dark". See Images and embeds for sizing and zoom options.

Tables

Tables hold the details readers come back for: status, limits, prices, and support across options. Lead with the table and keep prose around it short. For a page that is mostly tables, set mode: "wide" in the frontmatter to give them the full width. See Page mode.

Build these pages with an agent

Coding agents write widgets and recording scripts well when you give them the pattern and the data. Point the agent at this guide, then describe what you want the reader to understand.
Widget
Video
Before you publish:
  • Open the page with mint dev or in the editor, in light and dark mode.
  • Check that every widget renders and responds to clicks and to the keyboard.
  • Narrow the browser to phone width and check that nothing overflows.
  • Play each video and open each image.