Passer au contenu principal
Ajoutez des pages interactives pour permettre à vos lecteurs de parcourir un flux, d’utiliser des widgets ou de voir votre produit en action. Ce guide présente quatre éléments de base pour ces pages :
  1. Des widgets interactifs écrits dans la page sous forme de composants React.
  2. Des vidéos du produit, ou d’une session d’agent, enregistrées avec un script de navigateur.
  3. Des captures d’écran dans des cadres, en versions claire et sombre.
  4. Des tableaux pour les statuts, les limites et les comparaisons.
Les produits, les chiffres et les étapes des exemples de ce guide sont des données d’exemple.

Choisir un élément de base

Widgets interactifs

Un widget est un composant React déclaré dans la page avec export const, puis placé avec une balise comme <RxJourney />. Placez les définitions des composants à la fin du fichier pour que le contenu se lise de haut en bas. Consultez Composants React pour savoir ce que prend en charge l’environnement MDX.

Parcourir un flux

Utilisez un stepper lorsqu’un processus suit un ordre clair. Chaque étape indique qui agit et ce qui se passe.

Essayer ses propres chiffres

Utilisez une calculatrice lorsque la réponse dépend des valeurs saisies par le lecteur. Affichez la formule dans le résultat pour que les lecteurs puissent la vérifier.

Montrer une tendance

Utilisez un graphique avec un sélecteur lorsque les lecteurs basculent entre quelques séries liées. Limitez chaque graphique à une seule question.

Fonctionnement de la calculatrice

Voici le code source complet de la calculatrice. Les boutons de forfait, les curseurs et le résultat lisent tous l’état, et le total est calculé au rendu.
usage.mdx

Règles pour les widgets

  • Faites fonctionner chaque couleur en mode clair et en mode sombre. Utilisez currentColor ou inherit pour le texte et les traits, des gris translucides comme rgba(127,127,127,.25) pour les bordures et les remplissages, et une seule couleur d’accent. Évitez le noir ou le blanc fixes.
  • Ajoutez className="not-prose" à l’élément extérieur pour que les styles typographiques de la page ne modifient pas l’espacement dans le widget.
  • Écrivez les données dans le composant sous forme de constantes. Ne récupérez pas de données et n’utilisez pas localStorage, sessionStorage ni les cookies, car ils échouent ou ne font rien dans l’éditeur.
  • Écrivez du JavaScript simple. Une annotation TypeScript casse toute la page sur votre site publié.
  • Placez les liens dans le texte autour d’un widget. Les liens à l’intérieur d’un widget ne fonctionnent pas dans l’éditeur.
  • Donnez aux composants de chaque page un préfixe court commun, comme Rx, pour que leurs noms n’entrent pas en conflit avec les composants intégrés ni entre eux.
  • Donnez aux boutons et aux champs des libellés visibles ou un aria-label, et indiquez l’option sélectionnée avec aria-pressed ou aria-current.
  • Limitez chaque page à quelques widgets. L’éditeur exécute au maximum 10 widgets à la fois et met les autres en pause jusqu’à ce qu’ils apparaissent à l’écran.
  • Pour utiliser un widget sur plusieurs pages, déplacez-le dans un fichier sous /snippets/ et importez-le. Consultez Extraits réutilisables.

Vidéos

Enregistrez une courte vidéo lorsque les lecteurs doivent voir quelque chose bouger : la visite d’une interface, la fin d’un déploiement ou un agent qui accomplit une tâche. Les vidéos muettes en boucle fonctionnent comme des captures animées. Gardez les clips auto-hébergés courts et légers, et hébergez les vidéos plus longues sur une plateforme comme YouTube. Consultez Médias pour savoir quand utiliser la vidéo et comment réduire la taille des fichiers.

Enregistrer le produit avec un script

Un script de navigateur produit la même vidéo à chaque fois, ce qui vous permet de la réenregistrer après une modification de l’interface. Ce script Playwright enregistre un fichier WebM pendant qu’il parcourt un flux :
record.mjs
Conseils pour des enregistrements lisibles :
  • Faites une pause d’environ une seconde après chaque action, pour que les lecteurs puissent suivre le changement.
  • Saisissez le texte avec un délai au lieu de remplir les champs instantanément.
  • Gardez les vidéos sous 30 secondes. Découpez les flux plus longs en plusieurs vidéos placées à côté des étapes qu’elles montrent.
  • Utilisez des comptes et des données d’exemple, jamais des données de production.

Rejouer une session d’agent

Pour montrer ce qu’a fait un agent, enregistrez sa session et rejouez-la sous forme de vidéo. Claude Code et Codex peuvent écrire la session en lignes JSON, par exemple claude -p "<task>" --output-format stream-json --verbose > session.jsonl. Affichez les messages et les appels d’outils dans une page HTML simple de style terminal, puis enregistrez cette page avec le script Playwright. Une rediffusion montre les vraies commandes et l’ordre dans lequel l’agent les a exécutées, sans exposer de terminal en direct.

Captures d’écran

Placez les captures d’écran dans un <Frame> avec une légende qui indique quoi regarder. Recadrez sur la partie de l’écran qui compte.
Pour garder les captures à jour, prenez-les avec un script. Utilisez la même configuration Playwright que pour le script vidéo, appelez page.screenshot({ path: "images/settings-light.png" }) et relancez-le lorsque l’interface change. Pour la version sombre, créez le contexte avec colorScheme: "dark". Consultez Images et intégrations pour les options de taille et de zoom.

Tableaux

Les tableaux contiennent les détails que les lecteurs viennent rechercher : statuts, limites, prix et prise en charge selon les options. Commencez par le tableau et gardez le texte autour concis. Pour une page composée principalement de tableaux, définissez mode: "wide" dans le frontmatter pour leur donner toute la largeur. Consultez Mode de page.

Créer ces pages avec un agent

Les agents de code écrivent bien les widgets et les scripts d’enregistrement lorsque vous leur donnez le modèle et les données. Indiquez ce guide à l’agent, puis décrivez ce que vous voulez que le lecteur comprenne.
Widget
Video
Avant de publier :
  • Ouvrez la page avec mint dev ou dans l’éditeur, en mode clair et en mode sombre.
  • Vérifiez que chaque widget s’affiche et réagit aux clics et au clavier.
  • Réduisez le navigateur à la largeur d’un téléphone et vérifiez que rien ne déborde.
  • Lisez chaque vidéo et ouvrez chaque image.