MDX
Définition
Format de fichier qui combine Markdown et composants React dans un même document. Idéal pour les articles de blog qui ont besoin de blocs interactifs ou customisés.
Qu'est-ce que MDX
MDX combine la syntaxe Markdown (titres, listes, liens, citations, code, images) avec la possibilité d'utiliser des composants React directement dans le document. On écrit son contenu comme un article classique, et on insère un composant interactif (graphique, démo, formulaire, FAQ animée) là où c'est utile. Le fichier .mdx est compilé en composant React au build, ce qui combine la fluidité d'écriture du Markdown avec la puissance du JSX. C'est devenu un format de référence pour les blogs techniques, les documentations produit et les pages de contenu riches.
À quoi ça sert
MDX brille quand on a besoin de contenus riches sans passer par un CMS lourd. La rédaction reste fluide pour un développeur ou un rédacteur technique habitué au Markdown. Et on garde la porte ouverte à des blocs custom : un éditeur de code interactif, une démo live, un sondage, un encart de citation animé, un graphique. Pour une documentation technique ou un blog de développeur, MDX évite le compromis entre Markdown trop simple et HTML manuel trop verbeux. Le fichier reste lisible en source, ce qui aide à la maintenance.
Comment l'intégrer
Sur Next.js, plusieurs options. @next/mdx intègre MDX dans le pipeline du framework et permet d'utiliser .mdx comme des routes ou de les importer comme des composants. next-mdx-remote convient mieux quand les contenus viennent d'un CMS ou d'une base, et qu'on les rend à la volée. Contentlayer (et son fork actif Velite) ajoute du typage et une couche de validation Zod sur les fronts matter. Pour un blog avec quelques dizaines d'articles, l'approche fichiers .mdx dans le repo est imbattable de simplicité.
Front matter et métadonnées
Un fichier MDX commence souvent par un bloc YAML de métadonnées : title, description, date, author, tags, image. Ce front matter est extrait au build et utilisé pour générer la liste d'articles, le sitemap, les balises Open Graph, le balisage JSON-LD. On le valide avec Zod pour éviter qu'un article casse le site avec un champ manquant. La combinaison MDX + front matter validé donne un système de contenu typé et fiable, comparable à un mini-CMS en fichiers.
Quand utiliser autre chose
MDX n'est pas la solution universelle. Pour des articles très simples sans aucune interactivité, du Markdown classique suffit et reste plus portable. Pour des articles très interactifs où le contenu est secondaire, on bascule sur des composants React purs. Pour un site édité par des rédacteurs non techniques, on passe à un CMS headless (Sanity, Strapi, Storyblok) avec une UI dédiée. MDX est le bon choix quand l'équipe rédactionnelle accepte Git ou un éditeur basique, et que le contenu est suffisamment riche pour justifier les composants custom.
Les pièges à éviter
Trois pièges. La sur-personnalisation : ajouter dix composants custom différents par article rend le système ingérable, on se limite à une bibliothèque ciblée et stable. L'oubli des dépendances : un composant React utilisé dans un .mdx doit être importé ou injecté via le provider MDX, sinon le build casse. Le tracking de version : si on change l'API d'un composant utilisé dans 50 articles existants, on doit anticiper la migration. Pour limiter ces risques, on documente la bibliothèque de composants MDX comme un mini design system stable.