Markdown et MDX

Markdown (`.md`)

Le Markdown est une syntaxe de texte simple qui se convertit en HTML :

On écrit	On obtient
`## Titre de section`	Un titre de niveau 2 (et une entrée dans « Sur cette page »)
`gras`, `italique`	gras, italique
`code`	`code`
`[lien](/concepts/routing/)`	lien
`- élément`	Une liste à puces
`![texte alternatif](image.webp)`	Une image
`\| a \| b \|` sur plusieurs lignes	Un tableau, comme celui-ci

Les extensions de Starlight

Starlight ajoute au Markdown standard deux fonctionnalités, utilisables sans MDX :

Les encarts (asides), avec la syntaxe :::type … ::: :

Les blocs de code enrichis (moteur Expressive Code) : titre, lignes surlignées, ajouts et suppressions, bouton de copie.

```js title="exemple.js" {2} ins={3} del={4}
const a = 1;
const b = 2;   // ligne surlignée
const c = 3;   // ligne ajoutée
const d = 4;   // ligne supprimée
```

donne :

const a = 1;
const b = 2;   // ligne surlignée
const c = 3;   // ligne ajoutée
const d = 4;   // ligne supprimée

MDX (`.mdx`)

Le MDX est un sur-ensemble du Markdown : tout ce qui précède fonctionne aussi, avec en plus la possibilité d’importer et d’utiliser des composants :

---
title: Exemple
---

import { Tabs, TabItem } from '@astrojs/starlight/components';

Du Markdown normal, puis un composant :

<Tabs>
  <TabItem label="Linux">sudo apt install nodejs</TabItem>
  <TabItem label="macOS">brew install node</TabItem>
</Tabs>

Cette page-ci est elle-même en MDX : c’est ce qui lui permet d’afficher ces onglets :

Linux
macOS

sudo apt install nodejs

brew install node

…ou ce badge : MDX

Les composants disponibles sont présentés sur la page Composants Starlight.

Les pièges du MDX

En MDX, certains caractères ont un sens particulier hors des blocs de code :

{ et } délimitent une expression JavaScript ;
< ouvre une balise de composant.

Un texte comme a < b ou {valeur} écrit tel quel (ici protégé par des backticks) provoque donc une erreur de compilation. Il faut l’entourer de ` ou l’échapper (\{). Les règles propres au HTML en MDX sont détaillées dans HTML et styles personnalisés.

Lequel choisir ?

Critère	`.md`	`.mdx`
Simplicité, lisibilité	✅	⚠️
Encarts `:::note`, code enrichi	✅	✅
Composants (onglets, cartes…)	❌	✅
Édition dans un CMS	✅	⚠️
Tolérance aux caractères spéciaux	✅	❌