Plongée dans les composants MDX d'Explainer

L’une des plus grandes forces d’Explainer est sa bibliothèque de composants MDX. Chaque composant est auto-importé — aucune instruction d’import nécessaire — pour que vous puissiez vous concentrer sur le contenu, pas sur le boilerplate.

Dans cet article, nous parcourons chaque famille de composants, montrons des exemples pratiques et partageons des astuces pour en tirer le meilleur parti.

Callouts : guidez l’attention du lecteur

Les callouts sont le moyen le plus rapide de mettre en avant une information importante. Explainer supporte cinq variantes, chacune avec un style visuel distinct et une signification sémantique.

La syntaxe est simple :

:::callout{variant="warning" title="Changement majeur"}
L'option `config.legacy` a été supprimée dans la v2.
:::

Variantes disponibles : info, success, warning, danger et note. Chacune correspond à un jeu de couleurs qui fonctionne en mode clair comme sombre.

Cards et Card Groups : navigation structurée

Les cartes sont parfaites pour les aperçus de fonctionnalités, les collections de liens ou tout contenu qui bénéficie d’une mise en page en grille visuelle.

L’attribut cols sur card-group contrôle le nombre maximum de colonnes. Les cartes avec un attribut href deviennent des liens cliquables.

::::card-group{cols=2}
:::card{label="Démarrage rapide" icon="lucide:rocket" href="/fr/explainer/getting-started"}
Configurez Explainer en moins de 5 minutes.
:::

:::card{label="Configuration" icon="lucide:settings" href="/fr/explainer/configuration"}
Personnalisez chaque aspect de votre documentation.
:::
::::

Steps : instructions séquentielles

Lorsque vous documentez un processus, les steps fournissent une hiérarchie visuelle claire avec des indicateurs numérotés.

Les steps sont particulièrement utiles pour les guides de démarrage, les instructions d’installation et les tutoriels en plusieurs étapes.

Code Groups : comparez et contrastez

Les code groups permettent d’afficher plusieurs blocs de code dans une interface à onglets — idéal pour montrer le même concept dans différents langages ou configurations.

interface User {
  name: string
  email: string
}

class User:
    name: str
    email: str

type User struct {
    Name  string
    Email string
}

Les labels des onglets sont extraits de la syntaxe [label] dans la chaîne meta de chaque bloc de code. Les lecteurs peuvent passer d’un onglet à l’autre sans perdre leur position de défilement.

Blocs de code enrichis

Au-delà des code groups, les blocs de code d’Explainer supportent plusieurs améliorations nativement :

• Coloration syntaxique avec double thème (clair et sombre)
• Numéros de ligne pour référence
• Barres de titre affichant le nom du fichier
• Mise en surbrillance de lignes pour attirer l’attention
• 60+ icônes de langages affichées automatiquement

export async function fetchContributors(options?: FetchContributorsOptions): Promise<Contributor[]> {
  const owner = options?.owner ?? 'LeadcodeDev'
  const repo = options?.repo ?? 'explainer_v2'

  const response = await fetch(
    `https://api.github.com/repos/${owner}/${repo}/contributors?per_page=100`,
    { headers },
  )

  return response.json()
}

Combiner les composants

La vraie puissance vient de la combinaison des composants ensemble. Voici un pattern que nous utilisons fréquemment dans la documentation d’Explainer :

git clone https://github.com/LeadcodeDev/explainer_v2
cd explainer_v2 && pnpm install

pnpm dev

Et ensuite

Ces composants couvrent les patterns de documentation les plus courants. Si vous avez besoin de quelque chose de personnalisé, le pipeline MDX d’Explainer supporte aussi les composants React standards — importez-les et utilisez-les.

Nous serions ravis de voir ce que vous construisez avec ces composants. Partagez votre documentation avec nous sur GitHub !