Composants MDX

MDX est le format d’article par défaut de Lisible. Il conserve toute la syntaxe présentée dans Markdown enrichi et permet d’insérer des composants dans la prose. Chaque fiche ci-dessous montre le code complet à copier, puis son rendu réel immédiatement en dessous.

Imports

Les composants React et Astro doivent être importés après le frontmatter, avant le premier contenu. Un import n’ajoute aucun JavaScript au navigateur tant que le composant n’est pas utilisé. Les directives Markdown github et drawio sont fournies par le pipeline et ne nécessitent pas d’import.

Code

1
---
2
title: "Mon article interactif"
3
description: "Un exemple avec les composants MDX de Lisible."
4
pubDate: 2026-07-19
5
---
6

7
import { Tabs, Tab } from "@/components/ui/tabs";
8
import { Steps, Step } from "@/components/ui/steps";
9
import { Tree } from "@shared/components/ui/file-tree";
10
import Spoiler from "@/components/Spoiler.astro";
11
import Diagram from "@shared/components/Diagram.astro";

Rendu

Les imports ne produisent aucun élément visible. Ils rendent simplement Tree, Tabs, Tab, Steps, Step, Spoiler et Diagram disponibles pour les exemples placés après eux.

Arborescence de fichiers

Tree affiche une hiérarchie de fichiers interactive partagée par les six variantes. Chaque dossier peut être ouvert indépendamment, les fichiers peuvent être sélectionnés et le contrôle global déplie ou replie tous les dossiers. Utilisez-le pour une structure de projet où un arbre texte statique masquerait des détails utiles.

Chaque élément exige un id unique et un name. Définissez type à file ou folder ; un élément avec children est aussi reconnu comme dossier. isSelectable: false désactive la sélection tout en conservant l’élément dans la hiérarchie.

Dans un îlot MDX, utilisez "default" ou "none" pour sort, car Astro sérialise les propriétés entre serveur et client. Une fonction de comparaison doit rester dans un composant wrapper React.

Code

1
import { Tree } from "@shared/components/ui/file-tree";
2

3
<Tree
4
  client:load
5
  initialExpandedItems={["src", "pages"]}
6
  initialSelectedId="home"
7
  elements={[
8
    {
9
      id: "src",
10
      name: "src",
11
      type: "folder",
12
      children: [
13
        {
14
          id: "pages",
15
          name: "pages",
16
          type: "folder",
17
          children: [{ id: "home", name: "HomePage.astro", type: "file" }],
18
        },
19
        { id: "styles", name: "styles.css", type: "file" },
20
      ],
21
    },
22
    { id: "config", name: "lisible.config.json", type: "file" },
23
  ]}
24
/>

Rendu

Onglets

Tabs regroupe plusieurs contenus alternatifs sans allonger la page. Utilisez-le pour des commandes équivalentes, des variantes de configuration ou des exemples dans plusieurs langages. Chaque libellé de tabs correspond à un composant Tab, dans le même ordre.

Tab accepte le contenu MDX et une propriété className facultative. Conservez autant de Tab que de libellés : le composant associe les panneaux par leur position.

Code

1
import { Tabs, Tab } from "@/components/ui/tabs";
2

3
<Tabs
4
  tabs={["bun", "npm", "pnpm"]}
5
  label="Gestionnaire de paquets"
6
  defaultTab="npm"
7
  client:load
8
>
9
  <Tab>
10

11
  ```bash
12
  bun install
13
  bun run dev
14
  ```
15

16
  </Tab>
17
  <Tab>
18

19
  ```bash
20
  npm install
21
  npm run dev
22
  ```
23

24
  </Tab>
25
  <Tab>
26

27
  ```bash
28
  pnpm install
29
  pnpm dev
30
  ```
31

32
  </Tab>
33
</Tabs>

Rendu

bun install
bun run dev

npm install
npm run dev

pnpm install
pnpm dev

Le composant expose les rôles tablist, tab et tabpanel. Les flèches gauche et droite changent d’onglet, tandis que Home et End atteignent le premier et le dernier. Le label doit donc décrire le choix proposé, pas répéter « onglets ».

Étapes

Steps présente une procédure ordonnée avec une numérotation et un connecteur visuels. Chaque Step représente une action cohérente ; son titre doit commencer par un verbe et son corps peut contenir des paragraphes, listes, liens ou blocs de code.

Ce composant n’a pas d’état interactif : ne lui ajoutez pas de directive client:*. Il est rendu en HTML statique.

Code

1
import { Steps, Step } from "@/components/ui/steps";
2

3
<Steps>
4
  <Step title="Créer le miroir bilingue">
5

6
  Lancez `bun run new-post guide --translate` pour créer les deux fichiers `.mdx`.
7

8
  </Step>
9
  <Step title="Importer les composants">
10

11
  Placez les imports après le frontmatter, avant le premier paragraphe.
12

13
  </Step>
14
  <Step title="Valider le résultat">
15

16
  - testez le clavier ;
17
  - vérifiez les thèmes clair et sombre ;
18
  - exécutez le build statique.
19

20
  </Step>
21
</Steps>

Rendu

1. Créer le miroir bilingue

   Lancez bun run new-post guide --translate pour créer les deux fichiers .mdx.

2. Importer les composants

   Placez les imports après le frontmatter, avant le premier paragraphe.

3. Valider le résultat

   • testez le clavier ;
   • vérifiez les thèmes clair et sombre ;
   • exécutez le build statique.

Spoiler

Spoiler floute une réponse courte jusqu’au clic ou à l’activation avec Entrée ou Espace. Il accepte uniquement son contenu enfant et fonctionne sans directive d’hydratation, car son comportement est porté par le composant Astro.

Code

1
import Spoiler from "@/components/Spoiler.astro";
2

3
La réponse est <Spoiler>l’architecture en îlots</Spoiler>.

Rendu

La réponse est l’architecture en îlots.

Carte GitHub

La directive github transforme un identifiant propriétaire/dépôt en carte cliquable. Le lien fonctionne immédiatement, puis le script côté client enrichit la carte avec la description, le langage, les étoiles et les forks disponibles. Aucun import MDX n’est nécessaire.

Code

1
::github{repo="didntchooseaname/lisible-docs"}

Rendu

Utilisez une seule carte lorsque le dépôt est la destination principale. Pour une liste de références, de simples liens restent plus rapides à parcourir.

Diagramme draw.io

La directive drawio charge un export SVG créé avec draw.io dans une visionneuse dotée du zoom, du déplacement, de la réinitialisation et du plein écran. Le plein écran utilise la même API navigateur et le même overlay de repli que Mermaid, puis se ferme avec Échap. L’image Markdown placée dans la directive sert de repli si le chargement ou l’exécution du script échoue.

Le texte alternatif de l’image de repli doit décrire l’information du diagramme. Il ne doit pas se limiter à « diagramme » ou répéter le nom du fichier.

Code

1
:::drawio{src="/images/demo-ilots.svg" title="Pipeline en îlots"}
2
![Pipeline montrant le passage du contenu aux six variantes Astro](/images/demo-ilots.svg)
3
:::

Rendu

Schémas SVG intégrés

Diagram insère un schéma directement dans le HTML au lieu de le charger via <img>. C’est ce qui le rend vivant : un SVG inline hérite des variables CSS de la page, donc ses traits suivent l’accent choisi par le lecteur dans l’en-tête et ses surfaces suivent le thème actif, sans JavaScript et sans requête supplémentaire. Un SVG servi via <img> reste isolé de la page et ne peut pas faire cela.

Trois schémas sont fournis : islands, pipeline et tokens. Passez la locale pour que les libellés et la légende suivent l’article.

Code

1
import Diagram from "@shared/components/Diagram.astro";
2

3
<Diagram id="islands" locale="fr" />
4
<Diagram id="pipeline" locale="fr" caption="Du fichier source à la page servie." />

Rendu

Une figure avec légende, dimensionnée par ratio d’aspect afin de réserver sa place avant le premier rendu. Pour en ajouter, étendez la table copy et les branches de dessin dans shared/components/Diagram.astro.

Choisir l’hydratation

Une directive client:* ne se place que sur un composant de framework qui a besoin de JavaScript dans le navigateur. Les composants Astro comme Spoiler gèrent leurs scripts eux-mêmes, et les composants purement statiques comme Steps n’ont pas besoin d’hydratation.

Dans le doute, partez sans directive : ajoutez-en une uniquement lorsque le composant de framework contient un état, un événement ou une API navigateur qui doit fonctionner côté client.