Aller au contenu
Astro Astro

Markdown & MDX

Le Markdown est couramment utilisé pour créer des contenus à forte teneur en texte, tels que des articles de blog et de la documentation. Astro inclut une prise en charge intégrée des fichiers Markdown standard qui peuvent également inclure un frontmatter YAML pour définir des métadonnées personnalisées telles qu’un titre, une description et des balises.

Avec l’intégration @astrojs/mdx (EN) installée, Astro supporte aussi les fichiers MDX (.mdx) qui apportent des fonctionnalités supplémentaires, telles que la prise en charge des expressions et des composants JavaScript dans votre contenu Markdown.

Utilisez l’un ou les deux types de fichiers pour écrire du contenu Markdown !

Pages Markdown et MDX

Collections de contenu

Vous pouvez gérer vos fichiers Markdown et MDX dans Astro dans un dossier spécial src/content/. Les collections de contenu vous aident à organiser votre contenu, à valider vos frontmatter et fournir un type-safety TypeScript automatique lorsque que vous travaillez sur votre contenu.

  • Répertoiresrc/content/
    • Répertoirenewsletter/
      • week-1.md
      • week-2.md
    • Répertoireauthors/
      • grace-hopper.md
      • alan-turing.md

Pour en savoir plus sur l’utilisation des collections de contenu dans Astro.

Routage basé sur les fichiers

Astro traite n’importe quel fichier .md (ou une autre extension prise en charge) ou .mdx à l’intérieur du répertoire /src/pages/ comme une page.

Placer un fichier dans ce répertoire, ou dans un sous-répertoire, construira automatiquement une route vers cette page en utilisant le chemin du fichier.

src/pages/page-1.md
---
title: Hello, World
---


# Bonjour à tous !


Ce fichier Markdown créer une page à l'adresse `ton-domaine.com/page-1/`


Ce n'est probablement pas suffisamment stylisé, mais le Markdown supporte :
- **gras** et _italique._
- listes
- [liens](https://astro.build)
- Et plus encore !

📚 En savoir plus sur le routage basé sur les fichiers d’Astro ou les options pour créer des routes dynamiques.

Fonctionnalités de Markdown

Astro offre quelques fonctions Markdown supplémentaires intégrées, disponibles lors de l’utilisation de fichiers Markdown et MDX.

Frontmatter layout

Astro fournit aux pages Markdown et MDX une propriété spéciale layout qui peut spécifier un chemin relatif (ou alias) vers un composant de mise en page Astro.

src/pages/posts/post-1.md
---
layout: ../../layouts/BlogPostLayout.astro
title: Astro en bref
author: Himanshu
description: Découvrez ce qui rend Astro génial !
---
Il s'agit d'un billet écrit en Markdown.

Les propriétés spécifiques sont alors disponibles pour le composant de mise en page à travers Astro.props. Par exemple, vous pouvez accéder aux propriétés du frontmatter par l’intermédiaire de Astro.props.frontmatter:

src/layouts/BlogPostLayout.astro
---
const {frontmatter} = Astro.props;
---
<html>
  <!-- ... -->
  <h1>{frontmatter.title}</h1>
  <h2>Auteur de l'article : {frontmatter.author}</h2>
  <p>{frontmatter.description}</p>
  <slot /> <!-- Le contenu Markdown est injecté ici -->
   <!-- ... -->
</html>

Vous pouvez également styliser votre Markdown (EN) dans votre composant de mise en page.

📚 En savoir plus sur les mises en page Markdown.

Identifiants d’En-tête

L’utilisation d’en-tête en Markdown et MDX va automatiquement vous donner des liens d’ancrage afin que vous puissiez accéder directement à certaines sections de votre page.

src/pages/page-1.md
---
title: Ma page de contenu
---
## Introduction


Je peux créer des liens internes vers [ma conclusion](#conclusion) sur la même page lors de l'écriture en Markdown.


## Conclusion


Je peux utiliser l'URL `https://exemple.com/page-1/#introduction` pour naviguer directement vers mon Introduction sur la page.

Astro génère des ids de rubrique basés sur github-slugger. Vous pouvez trouver plus d’exemples dans la documentation de github-slugger.

Caractères spéciaux d’échappement

Certains caractères ont une signification spéciale en Markdown et MDX. Vous devez utiliser une syntaxe différente si vous souhaitez les afficher. Pour ce faire, vous pouvez utiliser les entités HTML à la place de ces caractères.

Par exemple, pour prévenir < d’être interprété comme le début d’une base HTML, écrivez &lt;. Ou, pour prévenir { d’être interprété comme le début d’une expression JavaScript en MDX, écrivez &lcub;.

Fonctionnalités MDX uniquement

L’ajout de l’intégration Astro MDX (EN) améliore votre création de Markdown avec des variables, des expressions et des composants JSX.

Il ajoute aussi des fonctionnalités supplémentaires au MDX standard, notamment la prise en charge du frontmatter de style Markdown dans MDX. Cela vous permet d’utiliser la plupart des fonctionnalités Markdown intégrées d’Astro, comme la propriété de frontmatter layout.

Les fichiers .mdx doivent être écrit dans la syntaxe MDX plutôt que dans la syntaxe de type HTML d’Astro.

Utilisation de variables exportées dans MDX

MDX permet d’utiliser l’instruction export pour ajouter des variables dans votre contenu MDX. Ces variables sont accessibles à la fois dans le modèle lui-même et comme propriétés nommées lors de l’importation du fichier à un autre endroit.

Par exemple, vous pouvez exporter un champ title depuis une page ou un composant MDX pour l’utiliser en tant qu’en-tête avec les {expressions JSX} :

/src/pages/posts/post-1.mdx
export const title = 'Mon premier billet sur le MDX'


# {title}

Utilisation de variables frontmatter en MDX

L’intégration MDX d’Astro inclut le support pour l’utilisation par défaut de frontmatter en MDX. Ajoutez les propriétés de frontmatter comme vous le feriez dans des fichiers Markdown, et ces variables sont accessibles pour être utilisées dans la template, dans son composant layout, et comme propriétés nommées lors de l’importation du fichier ailleurs.

/src/pages/posts/post-1.mdx
---
layout: '../../layouts/BlogPostLayout.astro'
title: 'Mon premier billet MDX'
---


# {frontmatter.title}

Utilisation des composants en MDX

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

N’oubliez pas d’inclure une client:directive sur les composants de votre framework d’interface utilisateur, si nécessaire !

Vous trouverez d’autres exemples d’utilisation des instructions d’importation et d’exportation dans la documentation MDX.

src/pages/about.mdx
---
layout: ../layouts/BaseLayout.astro
title: À propos de moi
---
import Button from '../components/Button.astro';
import ReactCounter from '../components/ReactCounter.jsx';


Je vis sur **Mars** mais n'hésitez pas à <Button title="Me contacter" />.


Voici mon composant compteur, fonctionnant en MDX :


<ReactCounter client:load />

Affectation de composants personnalisés à des éléments HTML

Avec MDX, vous pouvez associer la syntaxe Markdown à des composants personnalisés au lieu de 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 fait correspondre l’élément HTML standard à votre composant personnalisé :

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


> Cette citation sera un 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 /> <!-- N'oubliez pas d'ajouter un `<slot/>` pour le contenu enfant ! -->
</blockquote>

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

Importer du contenu Markdown

Vous pouvez importer des fichiers Markdown et MDX directement dans vos fichiers Astro. Cela vous donne accès à leur contenu Markdown, ainsi qu’à d’autres propriétés telles que les valeurs frontmatter qui peuvent être utilisées dans les expressions de type JSX d’Astro.

Vous pouvez importer une page spécifique avec une déclaration import ou plusieurs avec Astro.glob().

src/pages/index.astro
---
// Import d'un fichier
import * as myPost from '../pages/post/my-post.md';


// Import de plusieurs fichiers avec Astro.glob
const posts = await Astro.glob('../pages/post/*.md');
---

Quand vous importez des fichiers Markdown et MDX dans un composant Astro, vous obtenez un objet contenant leurs propriétés exportées.

/src/pages/posts/great-post.md
---
title: 'Le meilleur billet de tous les temps'
author: 'Ben'
---


Voici mon _incroyable_ billet !
src/pages/my-posts.astro
---
import * as greatPost from '../pages/post/great-post.md';


const posts = await Astro.glob('../pages/post/*.md');
---


<p>{greatPost.frontmatter.title}</p>
<p>Écrit par : {greatPost.frontmatter.author}</p>


<p>Archives de billets :</p>
<ul>
  {posts.map(post => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}
</ul>

Dans les fichiers MDX, vous pouvez accéder aux propriétés depuis le frontmatter et la déclaration export :

/src/pages/posts/mdx-post.mdx
---
title: 'Le meilleur billet de tous les temps'
author: 'Ben'
---
export const description = 'Mettez-vous à l'aise ! Cela va être une superbe lecture.'


Voici mon _super_ billet !
src/pages/my-posts.astro
---
import * as greatPost from '../pages/post/mdx-post.mdx';
---


<p>{greatPost.frontmatter.title}</p>
<p>Écrit par : {greatPost.frontmatter.author}</p>
<p>{greatPost.description}</p>

Vous pouvez éventuellement fournir un type pour la variable frontmatter en utilisant un générique TypeScript :

src/pages/index.astro
---
interface Frontmatter {
  title: string;
  description?: string;
}
const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
---


<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
  <!-- post.frontmatter.title va être une `string` ! -->
</ul>

Propriétés exportées

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

  • file - Le chemin absolu vers le fichier (par exemple /home/user/projects/.../file.md).
  • url - S’il s’agit d’une page, l’URL de la page (e.g. /fr/guides/markdown-content).
  • frontmatter - Contient toutes les données spécifiées dans le frontmatter YAML du fichier.
  • getHeadings - Une fonction asynchrone qui retourne un tableau de tous les titres (c.-à-d. les éléments h1 -> h6) du fichier. Le slug de chaque titre correspond à l’identifiant généré pour un titre donné et peut être utilisé pour les liens d’ancrage. Cette liste suit le type : { depth: number; slug: string; text: string }[].
  • Content - Un composant qui renvoie le contenu complet et rendu du fichier.
  • (Markdown uniquement) rawContent() - Une fonction qui renvoie le document Markdown brut sous forme de chaîne de caractères.
  • (Markdown uniquement) compiledContent() - Une fonction qui renvoie le document Markdown compilé en une chaîne HTML. Notez que cela n’inclut pas les mises en page configurées dans votre frontmatter ! Seul le document markdown lui-même sera renvoyé au format HTML.
  • (MDX uniquement) - Les fichiers MDX peuvent également exporter des données à l’aide de l’instruction export.

Le composant Content

Importer Content pour rendre un composant qui renvoie le contenu complet d’un fichier Markdown ou MDX :

src/pages/content.astro
---
import {Content as PromoBanner} from '../components/promoBanner.md';
---


<h2>Promotion du jour</h2>
<PromoBanner />

Exemple : Routage dynamique des pages

À la place de mettre vos fichiers Markdown/MDX dans le dossier src/pages/ pour créer des routes de pages, vous pouvez générer des pages dynamiquement.

Pour accéder à votre contenu Markdown, passez le composant <Content/> à travers le props de la page Astro. Vous pouvez alors récupérer le composant dans Astro.props et le rendre dans votre template.

src/pages/[slug].astro
---
export async function getStaticPaths() {
  const posts = await Astro.glob('../posts/**/*.md')


  return posts.map(post => ({
    params: {
      slug: post.frontmatter.slug
    },
    props: {
      post
    },
  }))
}


const { Content } = Astro.props.post
---
<article>
  <Content/>
</article>

Exportations MDX uniquement

Les fichiers MDX peuvent aussi exporter des données avec l’instruction export.

Par exemple, vous pouvez exporter un champ title depuis une page ou un composant MDX.

/src/pages/posts/post-1.mdx
export const title = 'Mon premier billet MDX'

Ce title sera accessible depuis les instructions import et Astro.glob() (EN) :

src/pages/index.astro
---
const posts = await Astro.glob('./*.mdx');
---


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

Composants personnalisés avec du MDX importé

Lors du rendu d’un 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 n'importe quel composant personnalisé défini dans `content.mdx` -->
<Content components={{...components, h1: Heading }} />

Configuration de Markdown et MDX

La prise en charge du Markdown dans astro est géré par remark, un outil puissant de parsing et de traitement doté d’un écosystème actif. D’autres parser de Markdown comme Pandoc et markdown-it ne sont pas supportés actuellement.

Astro applique par défaut les plugins Markdown de GitHub et SmartyPants. Cela permet de générer des liens cliquables à partir du texte et de mettre en forme les citations et les em-dashes.

Vous pouvez personnaliser la façon dont remark parse votre Markdown dans astro.config.mjs. Voir la liste complète des options de configuration Markdown (EN).

Plugins Markdown

Astro prend en charge l’ajout de plugins tiers remark et rehype pour Markdown et MDX. Ces plugins vous permettent d’ajouter de nouvelles fonctionnalités à votre Markdown, comme la génération automatique d’une table des matières, appliquer des étiquettes d’émoji accessibles et styliser votre markdown (EN).

Nous vous encourageons à consulter awesome-remark et awesome-rehype pour les plugins populaires ! Lisez le README de chaque plugin pour connaitre les instructions d’installation spécifiques.

Cet exemple applique remark-toc et rehype-accessible-emojis aux fichiers Markdown et MDX :

astro.config.mjs
import { defineConfig } from 'astro/config';
import remarkToc from 'remark-toc';
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';


export default defineConfig({
  markdown: {
    // Appliqué aux fichiers .md et .mdx
    remarkPlugins: [remarkToc],
    rehypePlugins: [rehypeAccessibleEmojis],
  },
});

Notez que par défaut, remarkToc nécessite un titre “ToC” ou “Table des matières” (insensible à la casse) sur la page pour afficher la table des matières.

ID de titres et plugins

Astro injecte un attribut id dans tous les éléments titre (<h1> à <h6>) dans les fichiers Markdown et MDX et fournit un utilitaire getHeadings() pour récupérer ces identifiants dans les propriétés Markdown exportées.

Vous pouvez personnaliser les ID de ces titres en ajoutant un plugin rehype qui injecte les attributs id (par exemple rehype-slug). Vos ID personnalisés, au lieu des valeurs par défaut d’Astro, seront reflétés dans la sortie HTML et dans les éléments retournés par getHeadings().

Par défaut, Astro injecte les attributs id après l’exécution de vos plugins rehype. Si l’un de vos plugins rehype personnalisés a besoin d’accéder aux ID injectés par Astro, vous pouvez importer et utiliser directement le plugin rehypeHeadingIds d’Astro. Assurez-vous d’ajouter rehypeHeadingIds avant tous les plugins qui en dépendent :

astro.config.mjs
import { defineConfig } from 'astro/config';
import { rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';


export default defineConfig({
  markdown: {
    rehypePlugins: [
      rehypeHeadingIds,
      otherPluginThatReliesOnHeadingIDs,
    ],
  },
});

Personnaliser un plugin

Pour personnaliser un plugin, il faut lui fournir un objet options dans un tableau imbriqué.

L’exemple ci-dessous ajoute l’option de titres au plugin remarkToc pour modifier l’emplacement de la table des matières, et l’option behavior au plugin rehype-autolink-headings afin d’ajouter la balise d’ancrage après le texte du titre.

astro.config.mjs
import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';


export default {
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: "contents"} ] ],
    rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
  },
}

Modifier le frontmatter par un programme

Vous pouvez ajouter des propriétés frontmatter à tout vos fichiers Markdown et MDX en utilisant un plugin remark ou rehype.

  1. Ajoutez un customProperty à la propriété data.astro.frontmatter de l’argument file de votre plugin :
example-remark-plugin.mjs
export function exampleRemarkPlugin() {
  // Tous les plugins remark et rehype renvoient une fonction distincte
  return function (tree, file) {
    file.data.astro.frontmatter.customProperty = 'Propriété générée';
  }
}

  1. Appliquez ce plugin à votre configuration d’intégration markdown ou mdx :

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
    

    export default defineConfig({
      markdown: {
        remarkPlugins: [exampleRemarkPlugin]
      },
    });

    ou

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
    

    export default defineConfig({
      integrations: [
        mdx({
          remarkPlugins: [exampleRemarkPlugin],
        }),
      ],
    });

Désormais, chaque fichier Markdown ou MDX contiendra customProperty dans son frontmatter, ce qui le rendra disponible lors de l’importation de votre markdown et depuis la propriété Astro.props.frontmatter dans vos layouts

Méthode associée : Ajout du temps de lecture

Extension de la configuration Markdown à partir de MDX

L’intégration MDX d’Astro étend par défaut la configuration Markdown existante de votre projet (EN). Pour remplacer des options individuelles, vous pouvez spécifier leur équivalent dans votre configuration MDX.

L’exemple suivant désactive le Markdown de Github et applique un panel différent de plugins remark pour les fichiers MDX :

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é de Markdown


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

Pour éviter d’étendre votre configuration Markdown à partir de MDX, mettez l’option extendMarkdownConfig (EN) (activée par défaut) à false :

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


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

Coloration syntaxique

Astro supporte nativement Shiki et Prism. Cela vous permet de profiter de la coloration syntaxique pour :

Shiki est activé par défaut, préconfiguré avec le thème github-dark. Le code compilé sera limité à des styles intégrés au HTML sans aucune classe CSS supplémentaire, ni feuilles de styles, ou JS sur le client.

Configuration de Shiki

Shiki est notre colorateur syntaxique par défaut. Vous pouvez configurer toutes les options via l’objet shikiConfig comme ci-après :

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  markdown: {
    shikiConfig: {
      // Choisissez parmi les thèmes intégrés de Shiki (ou ajoutez les vôtres)
      // https://github.com/shikijs/shiki/blob/main/docs/themes.md
      theme: 'dracula',
      // Alternativement, fournir plusieurs thèmes
      // https://github.com/antfu/shikiji#lightdark-dual-themes
      experimentalThemes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // Ajouter des langues personnalisées
      // Note : Shiki intègre d'innombrables langages, y compris le .astro !
      // https://github.com/shikijs/shiki/blob/main/docs/languages.md
      langs: [],
      // Activer le retour à la ligne automatique pour éviter le défilement horizontal
      wrap: true,
    },
  },
});

Ajouter votre propre thème

Au lieu d’utiliser l’un des thèmes prédéfinis de Shiki, vous pouvez importer un thème personnalisé à partir d’un fichier local.

astro.config.mjs
import { defineConfig } from 'astro/config';
import customTheme from './my-shiki-theme.json';


export default defineConfig({
  markdown: {
    shikiConfig: { theme: customTheme },
  },
});

Nous vous conseillons également de lire la documentation de Shiki sur les thèmes personnalisés pour en savoir plus sur les thèmes, les modes clair et sombre, ou le style via les variables CSS.

Modifier le mode par défaut de coloration syntaxique

Si vous souhaitez utiliser 'prism' par défaut, ou désactiver la coloration syntaxique entièrement, vous pouvez utiliser l’objet de configuration markdown.syntaxHighlighting :

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  markdown: {
    // Peut aussi être 'shiki' (par défaut), 'prism' ou false pour désactiver la coloration
    syntaxHighlight: 'prism',
  },
});

Configuration de Prism

Si vous choisissez d’utiliser Prism, Astro appliquera les classes CSS de Prism à la place. Notez que vous devez apporter votre propre feuille de style CSS pour que la coloration syntaxique apparaisse !

  1. Choisissez une feuille de style prédéfinie parmi les Thèmes Prism disponibles.
  2. Ajouter cette feuille de styles dans le répertoire public/ de votre projet.
  3. Chargez-la dans la balise <head> de votre page dans un composant de feuille de style via une balise <link>. (Voir utilisation basique de Prism.)

Vous pouvez aussi visiter la liste des langages supportés par Prism pour les options et leur usage.

Récupérer du Markdown distant

Astro a été principalement conçu pour les fichiers Markdown locaux qui peuvent être enregistrés dans le répertoire de votre projet. Toutefois, dans certains cas, il peut être nécessaire de récupérer le code Markdown à partir d’une source distante. Par exemple, vous pouvez avoir besoin de récupérer et de rendre du Markdown à partir d’une API distante lorsque vous compilez votre site web (ou lorsqu’un utilisateur fait une demande sur votre site web, en utilisant le SSR (EN)).

Astro ne comprend pas de support intégré pour le Markdown à distance ! Pour récupérer un fichier Markdown distant et le rendre au format HTML, vous devrez installer et configurer votre propre parser Markdown à partir de npm. Celui-ci n’héritera pas des paramètres intégrés Markdown et MDX d’Astro que vous avez configurés. Assurez-vous de bien comprendre ces limitations avant de l’intégrer à votre projet.

src/pages/remote-example.astro
---
// Exemple : Récupérer du Markdown à partir d'une API distante
// et le rendre en HTML au moment de l'exécution.
// En utilisant "marked" (https://github.com/markedjs/marked)
import { marked } from 'marked';
const response = await fetch('https://raw.githubusercontent.com/wiki/adam-p/markdown-here/Markdown-Cheatsheet.md');
const markdown = await response.text();
const content = marked.parse(markdown);
---
<article set:html={content} />