@astrojs/ mdx

Cette intégration Astro permet d’utiliser les composants MDX et de créer des pages sous forme de fichiers .mdx.

Pourquoi MDX ?

Titre de la section Pourquoi MDX ?

MDX vous permet d’utiliser des variables, des expressions JSX et des composants dans le contenu Markdown dans Astro. Si vous avez déjà du contenu rédigé en MDX, cette intégration vous permet d’intégrer ces fichiers dans votre projet Astro.

Installation

Titre de la section Installation

Astro inclut une commande astro add pour automatiser l’installation des intégrations officielles. Si vous préférez, vous pouvez installer les intégrations manuellement à la place.

Exécutez l’une des commandes suivantes dans une nouvelle fenêtre de terminal.

npm

npx astro add mdx

pnpm

pnpm astro add mdx

Yarn

yarn astro add mdx

Si vous rencontrez des problèmes, n’hésitez pas à nous les signaler sur GitHub et essayez les étapes d’installation manuelle ci-dessous.

Installation manuelle

Titre de la section Installation manuelle

Tout d’abord, installez le paquet @astrojs/mdx :

npm

npm install @astrojs/mdx

pnpm

pnpm add @astrojs/mdx

Yarn

yarn add @astrojs/mdx

Ensuite, appliquez l’intégration à votre fichier astro.config.* en utilisant la propriété integrations :

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
});

Intégration dans un éditeur

Titre de la section Intégration dans un éditeur

Pour la prise en charge de l’éditeur dans VS Code, installez l’extension MDX officielle.

Pour les autres éditeurs, utilisez le serveur de langage MDX.

Utilisation

Titre de la section Utilisation

Visitez le site MDX docs pour en savoir plus sur l’utilisation des fonctionnalités standard de MDX.

MDX dans Astro

Titre de la section MDX dans Astro

L’intégration de MDX permet d’améliorer la création de documents Markdown avec des variables, des expressions et des composants JSX.

Elle ajoute également des fonctionnalités supplémentaires au MDX standard, y compris la prise en charge de la syntaxe frontmatter de Markdown dans MDX. Cela vous permet d’utiliser la plupart des fonctionnalités Markdown intégrées à Astro.

Les fichiers .mdx doivent être écrits en syntaxe MDX plutôt qu’en syntaxe HTML d’Astro.

Utilisation de variables exportées dans MDX

Titre de la section Utilisation de variables exportées dans MDX

MDX permet d’utiliser les instructions export pour ajouter des variables à votre contenu MDX ou pour exporter des données vers un composant qui les importe.

Par exemple, vous pouvez exporter un champ title d’une page ou d’un composant MDX pour l’utiliser comme titre avec des {expressions JSX} :

/src/blog/posts/post-1.mdx

export const title = 'Mon tout premier post MDX';

# {title}

Ou vous pouvez utiliser ce title exporté dans votre page en utilisant les instructions import et import.meta.glob() :

src/pages/index.astro

---
const matches = await import.meta.glob('./posts/*.mdx', { eager: true });
const posts = Object.values(matches);
---

{posts.map(post => <p>{post.title}</p>)}

Propriétés exportées

Titre de la section Propriétés exportées

Les propriétés suivantes sont disponibles pour un composant .astro lorsqu’il utilise une instruction import ou import.meta.glob() :

• file - Le chemin absolu du fichier (par exemple /home/user/projects/.../file.mdx).
• url - L’URL de la page (par exemple /fr/guides/markdown-content).
• frontmatter - Contient toutes les données spécifiées dans le frontmatter YAML du fichier.
• getHeadings() - Une fonction asynchrone qui renvoie un tableau de tous les titres (<h1> à <h6>) dans le fichier avec le type : { depth: number ; slug: string ; text: string }[]. Le slug de chaque titre correspond à l’ID généré pour un titre donné et peut être utilisé pour les liens d’ancrage.
• <Content /> - Un composant qui renvoie le contenu complet et affiché du fichier.
• (toute valeur export) - Les fichiers MDX peuvent également exporter des données à l’aide d’une instruction export.

Utilisation de variables Frontmatter dans MDX

Titre de la section Utilisation de variables Frontmatter dans MDX

L’intégration MDX d’Astro inclut la prise en charge de l’utilisation de frontmatter dans MDX par défaut. Ajoutez des propriétés frontmatter comme vous le feriez dans des fichiers Markdown, et ces variables pourront être utilisées aussi bien dans le modèle qu’en tant que propriétés nommées lorsque vous importez le fichier ailleurs.

/src/blog/posts/post-1.mdx

---
title: 'Mon premier post MDX'
author: 'Houston'
---

# {frontmatter.title}

Écrit par : {frontmatter.author}

Utilisation de composants dans MDX

Titre de la section Utilisation de composants dans MDX

Après avoir installé l’intégration MDX, vous pouvez importer et utiliser les composants Astro et les composants du framework UI dans les fichiers MDX (.mdx) comme vous le feriez avec n’importe quel autre composant Astro.

N’oubliez pas de transmettre client:directive aux composants de votre framework UI, si nécessaire !

Vous trouverez d’autres exemples d’utilisation des instructions import et export dans la documentation de MDX.

src/blog/post-1.mdx

---
title: Mon premier article
---
import ReactCounter from '../components/ReactCounter.jsx';

Je viens de commencer mon nouveau blog avec Astro !

Voici mon composant compteur, fonctionnant en MDX :
<ReactCounter client:load />

Composants personnalisés avec MDX importé

Titre de la section Composants personnalisés avec MDX importé

Lors de l’affichage de contenu MDX importé, les composants personnalisés peuvent être passés via la propriété components.

src/pages/page.astro

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- Crée un <h1> personnalisé pour la syntaxe #, _et_ applique tout composant personnalisé défini dans `content.mdx` -->
<Content components={{...components, h1: Heading }} />

Note

Les composants personnalisés définis et exportés dans un fichier MDX doivent être importés et renvoyés au composant <Content /> via la propriété components.

Assigner des composants personnalisés à des éléments HTML

Titre de la section Assigner des composants personnalisés à des éléments HTML

Avec MDX, vous pouvez associer la syntaxe Markdown à des composants personnalisés plutôt qu’à leurs éléments HTML standard. Cela vous permet d’écrire dans la syntaxe Markdown standard, mais d’appliquer un style de composant spécial aux éléments sélectionnés.

Importez votre composant personnalisé dans votre fichier .mdx, puis exportez un objet components qui associe l’élément HTML standard à votre composant personnalisé :

src/blog/posts/post-1.mdx

import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> Cette citation utilisera un composant Blockquote personnalisé

src/components/Blockquote.astro

---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- Veillez à ajouter un `<slot/>` pour le contenu enfant ! -->
</blockquote>

Visitez le site web MDX pour obtenir la liste complète des éléments HTML qui peuvent être remplacés par des composants personnalisés.

Configuration

Titre de la section Configuration

Une fois l’intégration MDX installée, aucune configuration n’est nécessaire pour utiliser les fichiers .mdx dans votre projet Astro.

Vous pouvez configurer le rendu de votre MDX à l’aide des options suivantes :

• Options héritées de la configuration Markdown
• extendMarkdownConfig
• recmaPlugins
• optimize

Options héritées de la configuration Markdown

Titre de la section Options héritées de la configuration Markdown

Toutes les options de configuration markdown peuvent être configurées séparément dans l’intégration MDX. Cela inclut les plugins remark et rehype, la coloration syntaxique, et plus encore. Les options seront par défaut celles de votre configuration Markdown (voir l’option extendMarkdownConfig pour les modifier).

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypePresetMinify from 'rehype-preset-minify';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypePresetMinify],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});

Attention

MDX ne permet pas de fournir les plugins remark et rehype sous la forme d’une chaîne. Vous devez installer, importer et appliquer la fonction du plugin à la place.

Voir la référence des options Markdown pour une liste complète des options.

extendMarkdownConfig

Titre de la section extendMarkdownConfig

• Type : boolean
• Défaut : true

MDX étend par défaut la configuration Markdown existante de votre projet. Pour remplacer certaines options, vous pouvez spécifier leur équivalent dans votre configuration MDX.

Par exemple, disons que vous avez besoin de désactiver GitHub-Flavored Markdown et d’appliquer un ensemble différent de plugins de remark pour les fichiers MDX. Vous pouvez appliquer ces options comme suit, avec extendMarkdownConfig activée par défaut :

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // `syntaxHighlight` héritée de Markdown

      // Markdown `remarkPlugins` ignorée,
      // seulement `remarkPlugin2` est appliquée.
      remarkPlugins: [remarkPlugin2],
      // `gfm` remplacée par `false`
      gfm: false,
    }),
  ],
});

Vous pouvez également avoir besoin de désactiver l’extension de la configuration markdown dans MDX. Pour cela, mettez extendMarkdownConfig à false :

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // La configuration Markdown est désormais ignorée
      extendMarkdownConfig: false,
      // Pas de `remarkPlugins` appliquée
    }),
  ],
});

recmaPlugins

Titre de la section recmaPlugins

Il s’agit de plugins qui modifient directement la sortie estree. Ceci est utile pour modifier ou injecter des variables JavaScript dans vos fichiers MDX.

Nous vous suggérons d’utiliser AST Explorer pour jouer avec les sorties d’estree, et d’essayer estree-util-visit pour effectuer des recherches dans les nœuds JavaScript.

optimize

Titre de la section optimize

• Type : boolean | { ignoreElementNames?: string[] }

Il s’agit d’un paramètre de configuration facultatif qui permet d’optimiser la sortie MDX pour une construction et un rendu plus rapides grâce à un plugin rehype interne. Cela peut être utile si vous avez beaucoup de fichiers MDX et que vous constatez des lenteurs dans la construction. Cependant, cette option peut générer du HTML non échappé, assurez-vous donc que les parties interactives de votre site fonctionnent toujours correctement après l’avoir activée.

Cette option est désactivée par défaut. Pour activer l’optimisation MDX, ajoutez ce qui suit à votre configuration d’intégration MDX :

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});

ignoreElementNames

Titre de la section ignoreElementNames

• Type : string[]

Ajouté à la version : @astrojs/mdx@3.0.0

Précédemment connu sous le nom de customComponentNames.

Une propriété optionnelle de optimize pour empêcher l’optimiseur MDX de gérer certains noms d’éléments, comme les composants personnalisés passés au contenu MDX importé via la propriété components.

Vous devrez exclure ces composants de l’optimisation, car l’optimiseur convertit trop rapidement le contenu en une chaîne statique, ce qui brisera les composants personnalisés qui ont besoin d’être rendus dynamiquement.

Par exemple, la sortie MDX prévue pour ce qui suit est <Heading>...</Heading> à la place de chaque "<h1>...</h1>" :

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---

<Content components={{ ...components, h1: Heading }} />

Pour configurer l’optimisation à l’aide de la propriété ignoreElementNames, spécifiez un tableau de noms d’éléments HTML qui doivent être traités comme des composants personnalisés :

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // Empêcher l'optimiseur de traiter les éléments `h1`.
        ignoreElementNames: ['h1'],
      },
    }),
  ],
});

Notez que si votre fichier MDX configure les composants personnalisés en utilisant export const components = { ... }, alors vous n’avez pas besoin de configurer manuellement cette option. L’optimisateur les détectera automatiquement.

Exemples

Titre de la section Exemples

• Le modèle de démarrage Astro MDX montre comment utiliser les fichiers MDX dans votre projet Astro.

Plus d'intégrations

Framework d'interface utilisateur

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

Adaptateurs SSR

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

Autres intégrations

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind