Replace Asciinema players in docs

[milanholemans]

In the aftermath of #7118, let's look for something to replace Asciinema players in our docs. Suggestions like GIFs, YT videos, ... are welcome.

[Jwaegebaert]

I've been experimenting with a different approach, instead of swapping to another third-party tool (GIFs, YT embeds, etc.), what if we build a lightweight custom component that fits our exact use case?

The reality is that 90% of our Asciinema usage follows the same pattern: type a CLI command, show the JSON response. We don't need a full terminal emulator for that.

I'm testing a CommandPlayer React component. Here's what it does (or should do 😄):

How it works

• Renders a terminal-styled box that animates typing a command, then displays the JSON response with syntax highlighting
• Supports single commands or multi-step sequences (e.g., login > run command > show output)
• A remark plugin auto-extracts the JSON from the page's existing ## Response section at build time. No content duplication needed so easier to maintain
• Auto-loops with a clear animation between cycles

Why not GIFs / YouTube / another player?

	Downsides
GIFs	Large file sizes, no dark/light theme support, must be re-recorded on every change, not accessible, not searchable
YouTube	External dependency, overkill for a 5-second demo, cookie/privacy concerns, embed latency, must re-record on changes
Another terminal player	Same class of problems as Asciinema, external dependency, .cast/recording files to maintain, theme mismatch risk
Custom component	Zero dependencies, theme-aware, content stays in sync with docs, accessible, tiny footprint

What the prototype delivers

• Zero external dependencies (removes asciinema-player + all .cast files)
• Uses Docusaurus CSS variables > automatic light/dark mode support
• Respects prefers-reduced-motion > shows final state immediately for users who prefer no animation
• Full content in static HTML for SEO and screen readers
• ~400 lines of TypeScript/SCSS total, fully in our control
• Roughly ~5KB vs the ~200KB+ that asciinema-player added (JS + CSS + WASM)

Usage on a page

import CommandPlayer from 'src/components/CommandPlayer';

<CommandPlayer command='m365 planner task add --title "My task" --planId "abc123"' />

The response is auto-filled from the command page's ## Response JSON block. Nothing else to maintain.

Usage on overview pages (multi-step)

<CommandPlayer commands={[
  { command: 'm365 login', response: 'Logged in to Microsoft 365' },
  { command: 'm365 spo site list --type TeamSite', response: '[{ "Title": "Team Site", ... }]' }
]} />

Trade-offs to be aware of. This is a simulation, not a real terminal replay. no ANSI colors, interactive prompts, or progress bars. Currently auto-extracts JSON responses only (text/CSV would need a manual response prop or a plugin extension). And no playback controls (pause/scrub), just auto-play with looping

[milanholemans]

Does that mean that we'll have to create this component from scratch? Isn't it going to be quite some work to build this ourselves and maintain it through all future Docusaurus updates?

[Jwaegebaert]

It will take some effort to build, but the POC I’m working on already includes quite a few features and seems stable so far.

Future Docusaurus updates should not cause much trouble, since they are unlikely to affect this component. Only a Node update could potentially introduce some changes, but those are usually minor and not too complex to handle. This won't be a component that is swizzled or extracted from Docusaurus like the banner.

[milanholemans]

Cool, looking forward to seeing it in action 😊