Rédaction de guides et tutoriels plus riches avec des composants MDX

L’écriture en Markdown est bien pour la prose, mais les guides et les tutoriels ont généralement besoin de plus : un avertissement qui se démarque du paragraphe environnant, ou des options qui diffèrent selon le contexte ou l’environnement. Les messages dans src/content/posts peuvent maintenant être des fichiers .mdx, ce qui signifie qu’un article peut contenir des composants à côté de Markdown régulier sans aucune importation supplémentaire.

Cet article est lui-même un fichier .mdx, et chaque boîte ci-dessous est un rendu réel, pas une capture d’écran.

Appels

Utilisez <Callout> pour signaler quelque chose que le lecteur ne devrait pas manquer. L’attribut type choisit la couleur et l’étiquette par défaut ; title remplace l’étiquette si vous avez besoin de quelque chose de plus spécifique.

Exemples de code à onglets

Utilisez <CodeGroup> avec les enfants <CodeGroupItem> pour afficher la même étape sur quelques variantes, comme les gestionnaires de paquets, sans répéter la prose environnante trois fois.

npm install
npm run dev

pnpm install
pnpm dev

yarn install
yarn dev

Les onglets sont une amélioration progressive : un petit script en ligne construit la liste des onglets et cache les panneaux inactifs au chargement. Sans JavaScript, chaque panneau s’affiche toujours dans l’ordre avec une étiquette visible, de sorte que le contenu reste lisible de toute façon.

Mise en évidence de la syntaxe

Les blocs de code clôturés ordinaires n’ont pas du tout besoin d’un composant. Les articles .md et .mdx sont tous deux rendus via Shiki avec un double thème clair/sombre, de sorte qu’un bloc de code simple suit déjà le mode de couleur que le lecteur a choisi :

export function greet(name: string) {
  return `Hello, ${name}`;
}

Où les composants sont-ils situés ?

Les deux composants sont des fichiers .astro simples dans src/components/mdx, stylisés avec les mêmes jetons que le reste du thème, de sorte qu’ils captent automatiquement le mode clair et sombre. Ajoutez-en plus de la même manière : construisez le composant .astro, puis rendez-le disponible pour les messages via l’accessoire components transmis à <Content /> dans src/pages/post/[slug].astro.